chrome.cookies

الوصف

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

الأذونات

cookies

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

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

التقسيم

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

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

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

أمثلة

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

الأنواع

Cookie

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

أماكن إقامة

• نطاق

  سلسلة

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

• expirationDate

  الرقم اختياري

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

• hostOnly

  منطقي

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

• httpOnly

  منطقي

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

• الاسم

  سلسلة

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

• partitionKey

  CookiePartitionKey اختياري

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

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

• المسار

  سلسلة

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

• sameSite

  SameSiteStatus

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

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

• آمن

  منطقي

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

• جلسة

  منطقي

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

• storeId

  سلسلة

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

• القيمة

  سلسلة

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

CookieDetails

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

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

أماكن إقامة

• الاسم

  سلسلة

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

• partitionKey

  CookiePartitionKey اختياري

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

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

• storeId

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

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

• url

  سلسلة

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

CookiePartitionKey

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

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

أماكن إقامة

• hasCrossSiteAncestor

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

  في انتظار المراجعة

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

• topLevelSite

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

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

CookieStore

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

أماكن إقامة

• id

  سلسلة

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

• tabIds

  رقم[]

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

OnChangedCause

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

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

Enum

"expired_overwrite"

"overwrite"

SameSiteStatus

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

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

Enum

الطُرق

get()

Promise

chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

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

المعلمات

• التفاصيل

  CookieDetails

• رد الاتصال

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

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

  (cookie?: Cookie) => void

  • كعكة محلاة

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

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

المرتجعات

• Promise<Cookie | غير محددة>

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

  تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

getAll()

Promise

chrome.cookies.getAll(
  details: object,
  callback?: function,
)

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

المعلمات

• التفاصيل

  كائن

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

  • نطاق

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

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

  • الاسم

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

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

  • partitionKey

    CookiePartitionKey اختياري

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

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

  • المسار

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

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

  • آمن

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

    يؤدي هذا الخيار إلى فلترة ملفات تعريف الارتباط حسب موقعها الآمن.

  • جلسة

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

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

  • storeId

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

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

  • url

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

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

• رد الاتصال

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

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

  (cookies: Cookie[]) => void

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

    ملفات تعريف الارتباط[]

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

المرتجعات

• Promise<Cookie[]>

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

  تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

getAllCookieStores()

Promise

chrome.cookies.getAllCookieStores(
  callback?: function,
)

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

المعلمات

• رد الاتصال

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

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

  (cookieStores: CookieStore[]) => void

  • cookieStores

    CookieStore[]

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

المرتجعات

• Promise<CookieStore[]>

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

  تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

remove()

Promise

chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
)

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

المعلمات

• التفاصيل

  CookieDetails

• رد الاتصال

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

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

  (details?: object) => void

  • التفاصيل

    الكائن اختياري

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

    • الاسم

      سلسلة

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

    • partitionKey

      CookiePartitionKey اختياري

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

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

    • storeId

      سلسلة

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

    • url

      سلسلة

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

المرتجعات

• Promise<object | غير محددة>

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

  تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

set()

Promise

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

ضبط ملف تعريف ارتباط باستخدام بيانات ملف تعريف الارتباط المحدّدة؛ قد يستبدل ملفات تعريف الارتباط المكافئة في حالة وجودها.

المعلمات

• التفاصيل

  كائن

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

  • نطاق

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

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

  • expirationDate

    الرقم اختياري

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

  • httpOnly

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

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

  • الاسم

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

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

  • partitionKey

    CookiePartitionKey اختياري

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

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

  • المسار

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

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

  • sameSite

    SameSiteStatus اختياري

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

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

  • آمن

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

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

  • storeId

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

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

  • url

    سلسلة

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

  • القيمة

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

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

• رد الاتصال

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

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

  (cookie?: Cookie) => void

  • كعكة محلاة

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

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

المرتجعات

• Promise<Cookie | غير محددة>

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

  تتوفّر الوعود في الإصدار Manifest V3 والإصدارات الأحدث، ولكن يتم توفير معاودة الاتصال. التوافق مع الأنظمة القديمة. لا يمكنك استخدام كلتيهما في نفس استدعاء الدالة. تشير رسالة الأشكال البيانية يتم حل الوعد بنفس النوع الذي يتم إرساله إلى معاودة الاتصال.

الفعاليات

onChanged

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

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

المعلمات

• رد الاتصال

  دالة

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

  (changeInfo: object) => void

  • changeInfo

    كائن

    • السبب

      OnChangedCause

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

    • كعكة محلاة

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

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

    • تمت الإزالة

      منطقي

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