chrome.cookies

الوصف

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

الأذونات

cookies

البيان

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

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

التقسيم

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

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

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

أمثلة

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

الأنواع

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

الخصائص

  • نطاق

    سلسلة

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

  • expirationDate

    number اختياري

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

  • hostOnly

    قيمة منطقية

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

  • httpOnly

    قيمة منطقية

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

  • الاسم

    سلسلة

    تمثّل هذه السمة اسم ملف تعريف الارتباط.

  • partitionKey

    CookiePartitionKey اختياري

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

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

  • المسار

    سلسلة

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

  • sameSite

    SameSiteStatus

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

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

  • آمن

    قيمة منطقية

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

  • جلسة

    قيمة منطقية

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

  • storeId

    سلسلة

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

  • القيمة

    سلسلة

    تمثّل هذه السمة قيمة ملف تعريف الارتباط.

CookieDetails

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

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

الخصائص

  • الاسم

    سلسلة

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

  • partitionKey

    CookiePartitionKey اختياري

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

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

  • storeId

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

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

  • url

    سلسلة

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

CookiePartitionKey

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

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

الخصائص

  • hasCrossSiteAncestor

    boolean اختياري

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

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

  • topLevelSite

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

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

CookieStore

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

الخصائص

  • id

    سلسلة

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

  • tabIds

    number[]

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

FrameDetails

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

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

الخصائص

  • documentId

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

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

  • frameId

    number اختياري

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

  • tabId

    number اختياري

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

OnChangedCause

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

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

Enum

"evicted"

"منتهية الصلاحية"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

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

حالة 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()

الوعد 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
): Promise<Cookie | undefined>

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

المعلمات

  • التفاصيل

    CookieDetails

  • callback

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

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

    (cookie?: Cookie) => void

    • كعكة محلاة

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

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

المرتجعات

  • Promise<Cookie | undefined>

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

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

getAll()

الوعد 
chrome.cookies.getAll(
  details: object,
  callback?: function,
): Promise<Cookie[]>

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

المعلمات

  • التفاصيل

    عنصر

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

    • نطاق

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

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

    • الاسم

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

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

    • partitionKey

      CookiePartitionKey اختياري

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

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

    • المسار

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

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

    • آمن

      boolean اختياري

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

    • جلسة

      boolean اختياري

      فلترة ملفات تعريف ارتباط الجلسة مقابل ملفات تعريف الارتباط الدائمة

    • storeId

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

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

    • url

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

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

  • callback

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

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

    (cookies: Cookie[]) => void

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

      Cookie[]

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

المرتجعات

  • Promise<Cookie[]>

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

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

getAllCookieStores()

الوعد 
chrome.cookies.getAllCookieStores(
  callback?: function,
): Promise<CookieStore[]>

تعرِض هذه السمة جميع مستودعات ملفات تعريف الارتباط الحالية.

المعلمات

  • callback

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

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

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

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

المرتجعات

  • Promise<CookieStore[]>

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

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

getPartitionKey()

Promise Chrome 132 أو إصدار أحدث 
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
): Promise<object>

مفتاح القسم للإطار المحدّد

المعلمات

  • التفاصيل

    FrameDetails

  • callback

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

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

    (details: object) => void

    • التفاصيل

      عنصر

      يحتوي على تفاصيل حول مفتاح القسم الذي تم استرداده.

      • partitionKey

        CookiePartitionKey

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

المرتجعات

  • Promise<object>

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

remove()

الوعد 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
): Promise<object | undefined>

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

المعلمات

  • التفاصيل

    CookieDetails

  • callback

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

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

    (details?: object) => void

    • التفاصيل

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

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

      • الاسم

        سلسلة

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

      • partitionKey

        CookiePartitionKey اختياري

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

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

      • storeId

        سلسلة

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

      • url

        سلسلة

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

المرتجعات

  • Promise<object | undefined>

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

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

set()

الوعد 
chrome.cookies.set(
  details: object,
  callback?: function,
): Promise<Cookie | undefined>

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

المعلمات

  • التفاصيل

    عنصر

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

    • نطاق

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

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

    • expirationDate

      number اختياري

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

    • httpOnly

      boolean اختياري

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

    • الاسم

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

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

    • partitionKey

      CookiePartitionKey اختياري

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

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

    • المسار

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

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

    • sameSite

      SameSiteStatus اختيارية

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

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

    • آمن

      boolean اختياري

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

    • storeId

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

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

    • url

      سلسلة

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

    • القيمة

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

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

  • callback

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

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

    (cookie?: Cookie) => void

    • كعكة محلاة

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

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

المرتجعات

  • Promise<Cookie | undefined>

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

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

الفعاليات

onChanged

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

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

المعلمات

  • callback

    دالة

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

    (changeInfo: object) => void

    • changeInfo

      عنصر

      • السبب

        OnChangedCause

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

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

      • تمت الإزالة

        قيمة منطقية

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