browser.cookies

الوصف

يمكنك استخدام واجهة برمجة التطبيقات chrome.cookies للاستعلام عن ملفات تعريف الارتباط وتعديلها، ولتلقّي إشعارات عند تغييرها.

الأذونات

cookies

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

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

التقسيم

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

تعمل جميع طرق واجهة برمجة التطبيقات تلقائيًا على ملفات تعريف الارتباط غير المقسّمة. يمكن استخدام السمة partitionKey لتجاوز هذا السلوك.

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

أمثلة

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

الأنواع

Cookie

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

الخصائص

• نطاق

  سلسلة

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

• expirationDate

  number اختيارية

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

• hostOnly

  قيمة منطقية

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

• httpOnly

  قيمة منطقية

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

• الاسم

  سلسلة

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

• partitionKey

  CookiePartitionKey اختياري

  الإصدار 119 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

• المسار

  سلسلة

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

• sameSite

  SameSiteStatus

  الإصدار 51 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

• آمن

  قيمة منطقية

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

• جلسة

  قيمة منطقية

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

• storeId

  سلسلة

  معرّف مخزن ملفات تعريف الارتباط الذي يحتوي على ملف تعريف الارتباط هذا، كما هو موضّح في getAllCookieStores().

• القيمة

  سلسلة

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

CookieDetails

الإصدار 88 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

الخصائص

• الاسم

  سلسلة

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

• partitionKey

  CookiePartitionKey اختياري

  الإصدار 119 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

• storeId

  string اختياري

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

• url

  سلسلة

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

CookiePartitionKey

الإصدار 119 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

الخصائص

• hasCrossSiteAncestor

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

  الإصدار 130 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

• topLevelSite

  string اختياري

  الموقع الإلكتروني ذو المستوى الأعلى الذي يتوفّر فيه ملف تعريف الارتباط المُقسَّم.

CookieStore

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

الخصائص

• id

  سلسلة

  المعرّف الفريد لمخزن ملفات تعريف الارتباط

• tabIds

  number[]

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

FrameDetails

الإصدار 132 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

تفاصيل لتحديد الإطار

الخصائص

• documentId

  string اختياري

  المعرّف الفريد للمستند إذا تم تقديم frameId و/أو tabId، سيتم التحقّق من صحتهما لمطابقة المستند الذي تم العثور عليه من خلال رقم تعريف المستند المقدَّم.

• frameId

  number اختيارية

  المعرّف الفريد للإطار داخل علامة التبويب

• tabId

  number اختيارية

  المعرّف الفريد لعلامة التبويب التي تحتوي على الإطار

OnChangedCause

الإصدار 44 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

Enum

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

الإصدار 51 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

Enum

"no_restriction"

"lax"

"strict"

"unspecified"

الطُرق

get()

browser.cookies.get(
  details: CookieDetails,
): Promise<Cookie | undefined>

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

المعلمات

• التفاصيل

  CookieDetails

المرتجعات

• Promise<Cookie | undefined>

  الإصدار 88 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getAll()

browser.cookies.getAll(
  details: object,
): Promise<Cookie[]>

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

المعلمات

• التفاصيل

  عنصر

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

  • نطاق

    string اختياري

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

  • الاسم

    string اختياري

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

  • partitionKey

    CookiePartitionKey اختياري

    الإصدار 119 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

  • المسار

    string اختياري

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

  • آمن

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

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

  • جلسة

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

    يؤدي هذا الإجراء إلى فلترة ملفات تعريف الارتباط الخاصة بالجلسة مقابل ملفات تعريف الارتباط الدائمة.

  • storeId

    string اختياري

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

  • url

    string اختياري

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

المرتجعات

• Promise<Cookie[]>

  الإصدار 88 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getAllCookieStores()

browser.cookies.getAllCookieStores(): Promise<CookieStore[]>

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

المرتجعات

• Promise<CookieStore[]>

  الإصدار 88 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

getPartitionKey()

الإصدار 132 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

browser.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

مفتاح التقسيم للإطار المُشار إليه

المعلمات

• التفاصيل

  FrameDetails

المرتجعات

• وعد<كائن>

remove()

browser.cookies.remove(
  details: CookieDetails,
): Promise<object | undefined>

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

المعلمات

• التفاصيل

  CookieDetails

المرتجعات

• Promise<object | undefined>

  الإصدار 88 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

set()

browser.cookies.set(
  details: object,
): Promise<Cookie | undefined>

يتم ضبط ملف تعريف ارتباط باستخدام بيانات ملف تعريف الارتباط المحدّدة، وقد يتم استبدال ملفات تعريف الارتباط المكافئة إذا كانت متوفّرة.

المعلمات

• التفاصيل

  عنصر

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

  • نطاق

    string اختياري

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

  • expirationDate

    number اختيارية

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

  • httpOnly

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

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

  • الاسم

    string اختياري

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

  • partitionKey

    CookiePartitionKey اختياري

    الإصدار 119 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

  • المسار

    string اختياري

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

  • sameSite

    SameSiteStatus اختياري

    الإصدار 51 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

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

  • آمن

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

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

  • storeId

    string اختياري

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

  • url

    سلسلة

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

  • القيمة

    string اختياري

    قيمة ملف تعريف الارتباط يكون فارغًا تلقائيًا في حال عدم إدخال قيمة.

المرتجعات

• Promise<Cookie | undefined>

  الإصدار 88 من Chrome والإصدارات الأحدث browser.* ‎ منذ الإصدار 148 من Chrome

الفعاليات

onChanged

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

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

المعلمات

• callback

  دالة

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

  (changeInfo: object) => void

  • changeInfo

    عنصر

    • السبب

      OnChangedCause

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

    • كعكة محلاة

      Cookie

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

    • تمت الإزالة

      قيمة منطقية

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