chrome.cookies

الوصف

استخدِم واجهة برمجة التطبيقات chrome.cookies API لطلب ملفات تعريف الارتباط وتعديلها، وللحصول على إشعارات عند تغييرها.

الأذونات

cookies

البيان

لاستخدام واجهة برمجة التطبيقات cookies API، يجب الإفصاح عن إذن "ملفات تعريف الارتباط" في بيان التطبيق، بالإضافة إلى أذونات المضيف لأي مضيفين تريد الوصول إلى ملفات تعريف الارتباط الخاصة بهم. على سبيل المثال:

{
  "name": "My extension",
  ...
  "host_permissions": [
    "*://*.google.com/"
  ],
  "permissions": [
    "cookies"
  ],
  ...
}

التقسيم

تسمح ملفات تعريف الارتباط المقسَّمة للموقع الإلكتروني بوضع علامة على ضرورة إدخال ملفات تعريف ارتباط معينة مقابل أصل إطار المستوى الأعلى. وهذا يعني أنّه إذا تمّ تضمين الموقع الإلكتروني "أ" باستخدام إطار iframe في الموقع الإلكتروني "ب" والموقع الإلكتروني "ج"، يمكن أن يكون لملفات تعريف الارتباط المقسّمة قيمة مختلفة في كلّ موقع.

لا يتيح chrome.cookies التقسيم، ما يعني أنّ جميع الطرق غير متوافقة. قراءة وكتابة ملفات تعريف الارتباط من جميع الأقسام. تخزِّن طريقة cookies.set() ملفات تعريف الارتباط في القسم التلقائي.

للحصول على تفاصيل حول التأثير العام للتقسيم للحصول على الإضافات، يمكنك الاطّلاع على التخزين وملفات تعريف الارتباط:

أمثلة

يمكنك العثور على مثال بسيط لاستخدام واجهة برمجة التطبيقات الخاصة بملفات تعريف الارتباط في الدليل examples/api/cookies. للاطّلاع على أمثلة أخرى والحصول على مساعدة في الاطّلاع رمز المصدر، راجِع عيّنات.

الأنواع

يمثّل معلومات عن ملف تعريف ارتباط HTTP.

أماكن إقامة

  • نطاق

    سلسلة

    نطاق ملفّ تعريف الارتباط (مثل "www.google.com" أو "example.com")

  • expirationDate

    رقم اختياري

    تاريخ انتهاء صلاحية ملف تعريف الارتباط بالتنسيق: عدد الثواني منذ بدء حساب الفترة بتنسيق UNIX لا يتم توفيرها لملفات تعريف ارتباط الجلسة.

  • hostOnly

    منطقي

    صحيح إذا كان ملف تعريف الارتباط هو ملف تعريف ارتباط للمضيف فقط (أي أن مضيف الطلب يجب أن يطابق نطاق ملف تعريف الارتباط تمامًا).

  • httpOnly

    منطقي

    صحيح إذا تم وضع علامة على ملف تعريف الارتباط على أنّه HttpOnly (أي لا يمكن الوصول إلى ملف تعريف الارتباط من خلال النصوص البرمجية من جهة العميل).

  • الاسم

    سلسلة

    اسم ملفّ تعريف الارتباط.

  • partitionKey

    ‫CookiePartitionKey اختياري

    الإصدار 119 من Chrome والإصدارات الأحدث

    مفتاح القسم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة "مقسّمة"

  • المسار

    سلسلة

    مسار ملف تعريف الارتباط

  • سمة sameSite

    SameSiteStatus

    Chrome 51 والإصدارات الأحدث

    حالة ملف تعريف الارتباط على الموقع الإلكتروني نفسه (أي ما إذا كان يتم إرسال ملف تعريف الارتباط مع طلبات من مواقع إلكترونية مختلفة).

  • آمن

    منطقي

    صحيح إذا تم وضع علامة على ملف تعريف الارتباط على أنّه آمن (أي أنّ نطاقه يقتصر على القنوات الآمنة، عادةً HTTPS).

  • جلسة

    منطقي

    صحيح إذا كان ملف تعريف الارتباط لجلسة تشغيل، وليس ملف تعريف ارتباط دائم له تاريخ انتهاء صلاحية.

  • storeId

    سلسلة

    رقم تعريف متجر ملفات تعريف الارتباط الذي يحتوي على ملف تعريف الارتباط هذا، على النحو الوارد في getAllCookieStores()

  • القيمة

    سلسلة

    قيمة ملف تعريف الارتباط.

CookieDetails

الإصدار 88 من Chrome أو الإصدارات الأحدث

تفاصيل لتحديد ملف تعريف الارتباط

أماكن إقامة

  • الاسم

    سلسلة

    اسم ملف تعريف الارتباط المطلوب الوصول إليه.

  • partitionKey

    CookiePartitionKey اختياري

    الإصدار 119 من Chrome أو الإصدارات الأحدث

    مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة المقسَّمة.

  • storeId

    سلسلة اختيارية

    رقم تعريف متجر ملفات تعريف الارتباط الذي سيتم البحث فيه عن ملف تعريف الارتباط. وسيتم تلقائيًا استخدام مخزن ملفات تعريف الارتباط الخاص بسياق التنفيذ الحالي.

  • url

    سلسلة

    عنوان URL الذي يرتبط به ملف تعريف الارتباط المطلوب الوصول إليه. قد تكون هذه الوسيطة عنوان URL كاملًا، وفي هذه الحالة يتم ببساطة تجاهل أي بيانات تتّبع مسار عنوان URL (مثل سلسلة طلب البحث). إذا لم يتم تحديد أذونات المضيف لعنوان URL هذا في ملف البيان، سيتعذّر طلب البيانات من واجهة برمجة التطبيقات.

CookiePartitionKey

الإصدار 119 من Chrome والإصدارات الأحدث

يمثّل مفتاح قسم ملف تعريف ارتباط مُقسَّم.

أماكن إقامة

  • hasCrossSiteAncestor

    منطقي اختياري

    الإصدار 130 من Chrome أو الإصدارات الأحدث

    يشير إلى ما إذا تم ضبط ملف تعريف الارتباط في سياق مواقع إلكترونية متعددة. ويمنع ذلك الموقع الإلكتروني من المستوى الأعلى المضمّن في سياق على مستوى جميع المواقع الإلكترونية من الوصول إلى ملفات تعريف الارتباط التي ضبطها الموقع الإلكتروني من المستوى الأعلى في سياق الموقع الإلكتروني نفسه.

  • topLevelSite

    سلسلة اختيارية

    موقع المستوى الأعلى الذي يتوفّر فيه ملف تعريف الارتباط المقسّم.

CookieStore

يمثل مخزن ملفات تعريف الارتباط في المتصفح. على سبيل المثال، تستخدم نافذة وضع التصفّح المتخفي متجر ملفات تعريف ارتباط منفصلاً عن نافذة غير مزوّدة بوضع التصفّح المتخفي.

أماكن إقامة

  • id

    سلسلة

    المعرّف الفريد لمتجر ملفات تعريف الارتباط

  • tabIds

    رقم[]

    معرّفات كل علامات تبويب المتصفّح التي تشارك هذا المتجر لملفات تعريف الارتباط

OnChangedCause

Chrome 44 والإصدارات الأحدث

السبب الأساسي لتغيير ملف تعريف الارتباط. إذا تم إدراج ملف تعريف ارتباط أو إزالته من خلال طلب صريح إلى chrome.cookies.remove، سيكون السبب "واضحًا". إذا تمت إزالة ملف تعريف ارتباط تلقائيًا بسبب انتهاء الصلاحية، "السبب" سوف تكون "منتهي الصلاحية". إذا تمت إزالة ملف تعريف ارتباط بسبب استبداله بتاريخ انتهاء صلاحية منتهي الصلاحية بالفعل، "السبب" على "expired_over write". إذا تمت إزالة ملف تعريف ارتباط تلقائيًا بسبب تجميع البيانات غير المرغوب فيها، "السبب" "سيتم التخلص منها". إذا تمت إزالة ملف تعريف ارتباط تلقائيًا بسبب طلب "set" الذي أعاد كتابته، سيكون "سبب" الإزالة هو "إعادة الكتابة". وخطِّط ردّك وفقًا لذلك.

Enum

"evicted"

SameSiteStatus

Chrome 51 والإصدارات الأحدث

"SameSite" لملف تعريف الارتباط (https://tools.ietf.org/html/draft-west-first-party-cookies). يتوافق "no_restriction" مع ملف تعريف ارتباط تم ضبطه على "SameSite=None"، و"lax" مع "SameSite=Lax"، و"strict" مع "SameSite=Strict". "غير محدد" مع مجموعة ملفات تعريف ارتباط بدون سمة SameSite.

Enum

"lax"

الطُرق

get()

الوعد 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

لاسترداد معلومات حول ملف تعريف ارتباط واحد. في حالة وجود أكثر من ملف تعريف ارتباط واحد يحمل الاسم نفسه لعنوان URL المحدد، سيتم عرض الملف ذو أطول مسار. بالنسبة إلى ملفات تعريف الارتباط التي لها طول المسار نفسه، سيتم عرض ملف تعريف الارتباط الأقدم وقت إنشاء.

المعلمات

  • التفاصيل

    CookieDetails

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (cookie?: Cookie) => void

    • كعكة محلاة

      ملفات تعريف الارتباط اختيارية

      يحتوي على تفاصيل حول ملف تعريف الارتباط. تكون هذه المَعلمة فارغة في حال عدم العثور على ملفّ تعريف ارتباط من هذا النوع.

المرتجعات

  • تقديم وعود <ملفات تعريف الارتباط | غير محددة>

    الإصدار 88 من Chrome أو الإصدارات الأحدث

    لا تتوفّر الوعود إلا مع إصدار Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

getAll()

الوعد 
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

يسترجع جميع ملفات تعريف الارتباط من متجر ملفات تعريف ارتباط واحد تتطابق مع المعلومات المقدَّمة. سيتم فرز ملفات تعريف الارتباط التي تم إرجاعها، مع تحديد تلك الملفات ذات أطول مسار أولاً. إذا كانت هناك ملفات تعريف ارتباط متعددة لها طول المسار نفسه، ستكون ملفات تعريف الارتباط التي تم إنشاؤها في أقرب وقت هي الأولى. لا تستردّ هذه الطريقة سوى ملفات تعريف الارتباط للنطاقات التي تملك فيها الإضافة أذونات مضيف.

المعلمات

  • التفاصيل

    كائن

    معلومات لفلترة ملفات تعريف الارتباط التي يتم استرجاعها

    • نطاق

      سلسلة اختيارية

      يحدّ هذا الخيار من ملفات تعريف الارتباط التي يتم استرجاعها إلى تلك التي تتطابق نطاقاتها مع هذا النطاق أو هي نطاقات فرعية منه.

    • الاسم

      سلسلة اختيارية

      يصفي ملفات تعريف الارتباط حسب الاسم.

    • partitionKey

      ‫CookiePartitionKey اختياري

      الإصدار 119 من Chrome أو الإصدارات الأحدث

      مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة "مقسّمة"

    • المسار

      سلسلة اختيارية

      يحصر ملفات تعريف الارتباط التي يتم استرجاعها بتلك التي يتطابق مسارها تمامًا مع هذه السلسلة.

    • آمن

      قيمة منطقية اختيارية

      تصفية ملفات تعريف الارتباط حسب خاصيتها "آمنة"

    • جلسة

      قيمة منطقية اختيارية

      فلترة ملفات تعريف الارتباط الخاصة بالجلسة مقابل ملفات تعريف الارتباط الثابتة

    • storeId

      سلسلة اختيارية

      متجر ملفات تعريف الارتباط لاسترداد ملفات تعريف الارتباط منه في حال حذفها، سيتم استخدام مخزن ملفات تعريف الارتباط الخاص بسياق التنفيذ الحالي.

    • url

      سلسلة اختيارية

      يحصر ملفات تعريف الارتباط التي يتم استرجاعها بتلك التي تتطابق مع عنوان URL المحدّد.

  • ردّ الاتصال

    دالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (cookies: Cookie[]) => void

    • ملفات تعريف الارتباط

      Cookie[]

      جميع ملفات تعريف الارتباط الحالية غير المنتهية الصلاحية التي تتطابق مع معلومات ملفات تعريف الارتباط المحدّدة

المرتجعات

  • Promise<Cookie[]>

    الإصدار 88 من Chrome والإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

getAllCookieStores()

وعود 
chrome.cookies.getAllCookieStores(
  callback?: function,
)

يسرد جميع متاجر ملفات تعريف الارتباط الحالية.

المعلمات

  • ردّ الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      جميع مخازن ملفات تعريف الارتباط الحالية.

المرتجعات

  • Promise&lt;CookieStore[]&gt;

    الإصدار 88 من Chrome أو الإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

remove()

الوعد 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

حذف ملف تعريف الارتباط حسب الاسم.

المعلمات

  • التفاصيل

    CookieDetails

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (details?: object) => void

    • التفاصيل

      العنصر اختياري

      يحتوي على تفاصيل عن ملف تعريف الارتباط الذي تمّت إزالته. إذا تعذّرت الإزالة لأي سبب، ستكون القيمة "null"، وسيتم ضبط runtime.lastError.

      • الاسم

        سلسلة

        اسم ملفّ تعريف الارتباط الذي تمّت إزالته.

      • partitionKey

        CookiePartitionKey اختياري

        الإصدار 119 من Chrome أو الإصدارات الأحدث

        مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة "مقسّمة"

      • storeId

        سلسلة

        رقم تعريف متجر ملفات تعريف الارتباط الذي تمت إزالة ملف تعريف الارتباط منه.

      • url

        سلسلة

        عنوان URL المرتبط بملف تعريف الارتباط الذي تمّت إزالته.

المرتجعات

  • Promise<object | undefined>

    الإصدار 88 من Chrome أو الإصدارات الأحدث

    لا تتوفّر الوعود إلا مع إصدار Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.

set()

وعود 
chrome.cookies.set(
  details: object,
  callback?: function,
)

تُستخدَم لضبط ملفّ تعريف ارتباط باستخدام بيانات ملفّ تعريف الارتباط المحدّدة، وقد تستبدل ملفات تعريف الارتباط المماثلة في حال توفّرها.

المعلمات

  • التفاصيل

    كائن

    تفاصيل حول ملف تعريف الارتباط الذي يتمّ ضبطه

    • نطاق

      سلسلة اختيارية

      نطاق ملف تعريف الارتباط. في حال حذفه، يصبح ملف تعريف الارتباط خاصًا بالمضيف فقط.

    • expirationDate

      رقم اختياري

      تاريخ انتهاء صلاحية ملف تعريف الارتباط كعدد الثواني منذ حقبة UNIX. في حال حذفه، يصبح ملف تعريف الارتباط ملفّ تعريف ارتباط جلسة.

    • httpOnly

      منطقي اختياري

      لتحديد ما إذا كان يجب وضع علامة على ملف تعريف الارتباط كـ HttpOnly أم لا. القيمة التلقائية هي false.

    • الاسم

      سلسلة اختيارية

      اسم ملفّ تعريف الارتباط. وتكون فارغة إذا تم حذفها تلقائيًا.

    • partitionKey

      CookiePartitionKey اختياري

      الإصدار 119 من Chrome أو الإصدارات الأحدث

      مفتاح التقسيم لقراءة ملفات تعريف الارتباط أو تعديلها باستخدام السمة "مقسّمة"

    • المسار

      سلسلة اختيارية

      مسار ملف تعريف الارتباط الإعداد التلقائي هو جزء المسار من مَعلمة عنوان URL.

    • سمة sameSite

      SameSiteStatus اختياري

      الإصدار 51 من Chrome أو الإصدارات الأحدث

      حالة ملف تعريف الارتباط للموقع الإلكتروني نفسه. يتم ضبط القيمة التلقائية على "غير محدَّد"، أي في حال حذف ملف تعريف الارتباط، يتم ضبط ملف تعريف الارتباط بدون تحديد سمة SameSite.

    • آمن

      منطقي اختياري

      ما إذا كان يجب وضع علامة على ملف تعريف الارتباط باعتباره آمنًا القيمة التلقائية هي false.

    • storeId

      سلسلة اختيارية

      رقم تعريف ذاكرة تخزين ملفات تعريف الارتباط التي سيتم ضبط ملف تعريف الارتباط فيها. يتم ضبط ملف تعريف الارتباط تلقائيًا في ذاكرة ملفات تعريف الارتباط لسياق التنفيذ الحالي.

    • url

      سلسلة

      عنوان URI للطلب المراد ربطه بإعداد ملف تعريف الارتباط. يمكن أن تؤثر هذه القيمة في قيم النطاق والمسارات التلقائية لملف تعريف الارتباط الذي تم إنشاؤه. إذا لم يتم تحديد أذونات المضيف لعنوان URL هذا في ملف البيان، سيتعذّر طلب البيانات من واجهة برمجة التطبيقات.

    • القيمة

      سلسلة اختيارية

      قيمة ملف تعريف الارتباط. فارغ تلقائيًا في حال حذفه

  • رد الاتصال

    الدالة اختيارية

    تظهر المَعلمة callback على النحو التالي: 

    (cookie?: Cookie) => void

    • كعكة محلاة

      ملفات تعريف الارتباط اختيارية

      يحتوي على تفاصيل حول ملف تعريف الارتباط الذي تم ضبطه. إذا تعذّر ضبط الإعداد لأي سبب، ستكون القيمة "null"، وسيتم ضبط runtime.lastError.

المرتجعات

  • Promise<Cookie | undefined>

    الإصدار 88 من Chrome أو الإصدارات الأحدث

    لا تتوفّر الوعود إلا في الإصدار Manifest V3 والإصدارات الأحدث، ويجب أن تستخدم المنصات الأخرى طلبات الاستدعاء.

الفعاليات

onChanged

chrome.cookies.onChanged.addListener(
  callback: function,
)

يتم إطلاقها عند ضبط ملف تعريف ارتباط أو إزالته. وكحالة خاصة، تجدر الإشارة إلى أنّ تحديث خصائص ملفّ تعريف الارتباط يتمّ تنفيذه في عملية من خطوتَين: أولاً، تتمّ إزالة ملفّ تعريف الارتباط المطلوب تحديثه بالكامل، ويتمّ إنشاء إشعار بالسبب "السبب". "الاستبدال" . بعد ذلك، تتم كتابة ملف تعريف ارتباط جديد بالقيم المحدَّثة، ما يؤدي إلى إنشاء إشعار ثانٍ بعنوان "السبب". "فاضح".

المعلمات

  • رد الاتصال

    دالة

    تظهر المَعلمة callback على النحو التالي: 

    (changeInfo: object) => void

    • changeInfo

      كائن

      • السبب

        OnChangedCause

        السبب الأساسي لتغيير ملف تعريف الارتباط

      • كعكة محلاة

        Cookie

        معلومات عن ملفّ تعريف الارتباط الذي تمّ إعداده أو إزالته.

      • تمت الإزالة

        منطقي

        صحيح إذا تمّت إزالة ملفّ تعريف ارتباط.