الوصف
استخدِم واجهة برمجة تطبيقات chrome.cookies
لطلب البحث عن ملفات تعريف الارتباط وتعديلها، وتلقّي إشعارات عند تغييرها.
الأذونات
cookies
البيان
لاستخدام واجهة برمجة تطبيقات ملفات تعريف الارتباط، يجب تقديم بيان عن إذن "ملفات تعريف الارتباط" في البيان، إلى جانب أذونات المضيف لأي مضيف تريد الوصول إلى ملفات تعريف الارتباط الخاصة به. مثلاً:
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
التقسيم
تتيح ملفات تعريف الارتباط المقسَّمة للموقع الإلكتروني تحديد ضرورة قفل بعض ملفات تعريف الارتباط وفقًا لأصل إطار المستوى الأعلى. وهذا يعني أنّه في حال تضمين الموقع الإلكتروني "أ" باستخدام إطار iframe في الموقع الإلكتروني "ب" والموقع الإلكتروني "ج"، يمكن أن يحصل ملف تعريف الارتباط المقسّم على قيمة مختلفة في كلّ منهما.
لا تتيح "chrome.cookies
" ميزة التقسيم، ما يعني أنّه يتم قراءة ملفات تعريف الارتباط وكتابتها من جميع الأقسام على جميع الطرق. تخزِّن طريقة cookies.set()
ملفات تعريف الارتباط
في القسم التلقائي.
للحصول على تفاصيل حول التأثير العام لتقسيم الإضافات، يمكنك الاطّلاع على مساحة التخزين وملفات تعريف الارتباط.
أمثلة
يمكنك العثور على مثال بسيط لاستخدام واجهة برمجة تطبيقات ملفات تعريف الارتباط في دليل examples/api/cookies. للحصول على أمثلة أخرى والحصول على مساعدة في عرض رمز المصدر، راجع عيّنات.
الأنواع
Cookie
تمثل هذه السمة معلومات عن ملف تعريف ارتباط HTTP.
أماكن إقامة
-
نطاق
سلسلة
نطاق ملف تعريف الارتباط (على سبيل المثال "www.google.com" أو "example.com").
-
expirationDate
الرقم اختياري
تاريخ انتهاء صلاحية ملف تعريف الارتباط كعدد الثواني منذ حقبة UNIX. لا تتوفر لملفات تعريف الارتباط للجلسة.
-
hostOnly
boolean
صحيح إذا كان ملف تعريف الارتباط هو ملف تعريف ارتباط للمضيف فقط (أي يجب أن يتطابق مضيف الطلب تمامًا مع نطاق ملف تعريف الارتباط).
-
httpOnly
boolean
صحيح إذا تم تمييز ملف تعريف الارتباط على أنّه HttpOnly (أي يتعذّر على النصوص البرمجية من جهة العميل الوصول إلى ملف تعريف الارتباط).
-
اسم
سلسلة
اسم ملف تعريف الارتباط.
-
partitionKey
CookiePartitionKey اختياري
Chrome 119 والإصدارات الأحدثمفتاح القسم لقراءة أو تعديل ملفات تعريف الارتباط باستخدام السمة "مُقسَّم".
-
المسار
سلسلة
مسار ملف تعريف الارتباط.
-
sameSiteChrome 51 والإصدارات الأحدث
حالة الموقع الإلكتروني نفسه لملف تعريف الارتباط (أي ما إذا كان يتم إرسال ملف تعريف الارتباط مع طلبات من مواقع إلكترونية متعددة)
-
آمن
boolean
صحيح في حال وضع علامة على ملف تعريف الارتباط تفيد بأنّه "آمن" (أي أنّ نطاقه يقتصر على القنوات الآمنة، عادةً HTTPS).
-
جلسة
boolean
صحيح إذا كان ملف تعريف الارتباط هو ملف تعريف ارتباط للجلسة، على عكس ملف تعريف ارتباط دائم له تاريخ انتهاء صلاحية.
-
storeId
سلسلة
رقم تعريف مخزن ملفات تعريف الارتباط الذي يحتوي على ملف تعريف الارتباط هذا، على النحو الوارد في getAllCookieStores().
-
القيمة
سلسلة
قيمة ملف تعريف الارتباط.
CookieDetails
تفاصيل تحديد ملف تعريف الارتباط.
أماكن إقامة
-
اسم
سلسلة
اسم ملف تعريف الارتباط المطلوب الوصول إليه.
-
partitionKey
CookiePartitionKey اختياري
Chrome 119 والإصدارات الأحدثمفتاح القسم لقراءة أو تعديل ملفات تعريف الارتباط باستخدام السمة "مُقسَّم".
-
storeId
سلسلة اختيارية
رقم تعريف مخزن ملفات تعريف الارتباط حيث يتم البحث عن ملف تعريف الارتباط. وسيتم بشكل تلقائي استخدام مخزن ملفات تعريف الارتباط لسياق التنفيذ الحالي.
-
url
سلسلة
عنوان URL الذي يرتبط به ملف تعريف الارتباط الذي سيتم الوصول إليه. قد تكون هذه الوسيطة عنوان URL كامل، وفي هذه الحالة يتم تجاهل أي بيانات تتبع مسار عنوان URL (مثل سلسلة طلب البحث). وإذا لم يتم تحديد أذونات المضيف لعنوان URL هذا في ملف البيان، سيتعذّر تنفيذ طلب البيانات من واجهة برمجة التطبيقات.
CookiePartitionKey
يمثل مفتاح قسم ملف تعريف ارتباط مُقسَّم.
أماكن إقامة
-
topLevelSite
سلسلة اختيارية
الموقع الإلكتروني ذو المستوى الأعلى الذي يتوفّر فيه ملف تعريف الارتباط المقسّم.
CookieStore
يعرض هذا الخيار مخزنًا لملفات تعريف الارتباط في المتصفح. على سبيل المثال، تستخدم نافذة وضع التصفح المتخفي مخزنًا منفصلاً لملفات تعريف الارتباط من نافذة غير التصفح المتخفي.
أماكن إقامة
-
id
سلسلة
المعرّف الفريد لتخزين ملفات تعريف الارتباط.
-
tabIds
الرقم[]
معرّفات جميع علامات تبويب المتصفّح التي تشارك ملف تعريف الارتباط هذا
OnChangedCause
السبب الأساسي وراء تغيير ملف تعريف الارتباط. في حال إدراج ملف تعريف ارتباط أو إزالته من خلال طلب صريح للأمر "chrome.cookies.remove"، ستظهر كلمة "سبب" كلمة "فاضح". إذا تمت إزالة ملف تعريف ارتباط تلقائيًا بسبب انتهاء الصلاحية، فإن كلمة "السبب" ستكون "انتهت الصلاحية". في حال إزالة ملف تعريف ارتباط بسبب استبداله بتاريخ انتهاء صلاحية منتهي الصلاحية، سيتم ضبط "السبب" على "expired_over تحديث". إذا تمت إزالة ملف تعريف ارتباط تلقائيًا بسبب جمع البيانات غير المرغوب فيها، سيتم "طرد" "السبب". إذا تمت إزالة ملف تعريف ارتباط تلقائيًا بسبب طلب "محدد" استبدله، فإن كلمة "السبب" ستكون "استبدال". خطط للرد وفقًا لذلك.
التعداد
SameSiteStatus
حالة "SameSite" لملف تعريف الارتباط (https://tools.ietf.org/html/draft-west-first-party-cookies). تتوافق "no_restriction" مع ملف تعريف ارتباط تم ضبطه على "SameSite=None" و"lax" على "SameSite=Lax" و"strict" مع "SameSite=exact". تتوافق الحالة "غير محدّد" مع ملف تعريف ارتباط تم ضبطه بدون السمة SameSite.
التعداد
"no_restriction"
"lax"
الطُرق
get()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
)
يسترد معلومات حول ملف تعريف ارتباط واحد. وفي حال وجود أكثر من ملف تعريف ارتباط واحد يحمل الاسم نفسه لعنوان URL المحدّد، سيتم عرض الملف الذي يتضمّن أطول مسار. وبالنسبة إلى ملفات تعريف الارتباط التي لها طول المسار نفسه، سيتم عرض ملف تعريف الارتباط الذي له أقرب وقت للإنشاء.
المَعلمات
-
التفاصيل
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(cookie?: Cookie) => void
-
كعكة محلاة
ملف تعريف الارتباط اختياري
يحتوي على تفاصيل حول ملف تعريف الارتباط. وتكون هذه المَعلمة فارغة في حال عدم العثور على ملفّ تعريف الارتباط كهذا.
-
المرتجعات
-
Promise<Cookie | undefined>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
استرداد جميع ملفات تعريف الارتباط من مخزن واحد لملفات تعريف الارتباط، والذي يطابق المعلومات المحددة وسيتم ترتيب ملفات تعريف الارتباط التي يتم عرضها، مع تلك التي تحتوي على المسار الأطول أولاً. وإذا كانت ملفات تعريف الارتباط متعددة لها طول المسار نفسه، ستكون الملفات التي لها أقرب وقت للإنشاء هي أولاً. تسترد هذه الطريقة ملفات تعريف الارتباط للنطاقات التي تمتلك الإضافة أذونات المضيف لها.
المَعلمات
-
التفاصيل
عنصر
معلومات لفلترة ملفات تعريف الارتباط التي يتم استردادها.
-
نطاق
سلسلة اختيارية
يؤدي هذا الخيار إلى حصر ملفات تعريف الارتباط التي يتم استردادها بالملفات التي تتطابق نطاقاتها أو نطاقاتها الفرعية مع هذا النطاق.
-
اسم
سلسلة اختيارية
تتم فلترة ملفات تعريف الارتباط حسب الاسم.
-
partitionKey
CookiePartitionKey اختياري
Chrome 119 والإصدارات الأحدثمفتاح القسم لقراءة أو تعديل ملفات تعريف الارتباط باستخدام السمة "مُقسَّم".
-
المسار
سلسلة اختيارية
يتم حصر ملفات تعريف الارتباط التي تم استردادها على الملفات التي يتطابق مسارها تمامًا مع هذه السلسلة.
-
آمن
منطقية اختيارية
تتم فلترة ملفات تعريف الارتباط حسب الموقع الإلكتروني الآمن.
-
جلسة
منطقية اختيارية
تؤدي إلى فلترة ملفات تعريف الارتباط للجلسة مقابل ملفات تعريف الارتباط الدائمة.
-
storeId
سلسلة اختيارية
مخزن ملفات تعريف الارتباط لاسترداد ملفات تعريف الارتباط منه. وفي حال حذفه، سيتم استخدام ملف تعريف الارتباط الخاص بسياق التنفيذ الحالي.
-
url
سلسلة اختيارية
تحصر ملفات تعريف الارتباط التي تم استردادها تلك الملفات التي تتطابق مع عنوان URL المحدّد.
-
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(cookies: Cookie[]) => void
-
ملفات تعريف الارتباط
جميع ملفات تعريف الارتباط الحالية غير المنتهية الصلاحية والتي تتطابق مع معلومات ملفات تعريف الارتباط المقدَّمة
-
المرتجعات
-
Promise<Cookie[]>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
يسرد جميع مخازن ملفات تعريف الارتباط الحالية.
المَعلمات
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(cookieStores: CookieStore[]) => void
-
cookieStores
جميع مخازن ملفات تعريف الارتباط الحالية.
-
المرتجعات
-
Promise<CookieStore[]>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
remove()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
)
حذف ملف تعريف ارتباط حسب الاسم.
المَعلمات
-
التفاصيل
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(details?: object) => void
-
التفاصيل
الكائن اختياري
يحتوي على تفاصيل حول ملف تعريف الارتباط الذي تمت إزالته. وإذا تعذّرت الإزالة لأي سبب، ستكون هذه القيمة "فارغة"، وسيتم ضبط
runtime.lastError
.-
اسم
سلسلة
اسم ملف تعريف الارتباط الذي تمت إزالته.
-
partitionKey
CookiePartitionKey اختياري
Chrome 119 والإصدارات الأحدثمفتاح القسم لقراءة أو تعديل ملفات تعريف الارتباط باستخدام السمة "مُقسَّم".
-
storeId
سلسلة
رقم تعريف متجر ملفات تعريف الارتباط الذي تمت إزالة ملف تعريف الارتباط منه
-
url
سلسلة
عنوان URL المرتبط بملف تعريف الارتباط الذي تمت إزالته.
-
-
المرتجعات
-
Promise<object | undefined>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
set()
chrome.cookies.set(
details: object,
callback?: function,
)
لضبط ملف تعريف ارتباط ببيانات ملفات تعريف الارتباط المحددة، وقد يؤدي إلى استبدال ملفات تعريف الارتباط المكافئة في حال توفّرها.
المَعلمات
-
التفاصيل
عنصر
تفاصيل عن ملف تعريف الارتباط الذي يتم ضبطه
-
نطاق
سلسلة اختيارية
نطاق ملف تعريف الارتباط. وفي حال إسقاطه، يصبح ملف تعريف الارتباط ملف تعريف ارتباط للمضيف فقط.
-
expirationDate
الرقم اختياري
تاريخ انتهاء صلاحية ملف تعريف الارتباط كعدد الثواني منذ حقبة UNIX. وفي حال حذفه، يصبح ملف تعريف الارتباط ملف تعريف ارتباط للجلسة.
-
httpOnly
منطقية اختيارية
ما إذا كان يجب وضع علامة HttpOnly على ملف تعريف الارتباط. يكون الإعداد التلقائي بالقيمة "خطأ".
-
اسم
سلسلة اختيارية
اسم ملف تعريف الارتباط. يكون هذا الحقل فارغًا تلقائيًا إذا تم حذفه.
-
partitionKey
CookiePartitionKey اختياري
Chrome 119 والإصدارات الأحدثمفتاح القسم لقراءة أو تعديل ملفات تعريف الارتباط باستخدام السمة "مُقسَّم".
-
المسار
سلسلة اختيارية
مسار ملف تعريف الارتباط. يتم ضبط الإعداد التلقائي على جزء المسار من معلَمة عنوان URL.
-
sameSite
SameSiteStatus اختيارية
Chrome 51 والإصدارات الأحدثحالة الموقع الإلكتروني نفسه لملف تعريف الارتباط. يتم ضبط القيمة تلقائيًا على "غير محدَّد"، أي في حال حذف ملف تعريف الارتباط، يتم ضبط ملف تعريف الارتباط بدون تحديد سمة SameSite.
-
آمن
منطقية اختيارية
ما إذا كان يجب وضع علامة "آمن" على ملفّ تعريف الارتباط يكون الإعداد التلقائي بالقيمة "خطأ".
-
storeId
سلسلة اختيارية
رقم تعريف مخزن ملفات تعريف الارتباط الذي يتم فيه إعداد ملف تعريف الارتباط. ويتم ضبط ملف تعريف الارتباط تلقائيًا في مخزن ملفات تعريف الارتباط لسياق التنفيذ الحالي.
-
url
سلسلة
عنوان URI للطلب المطلوب ربطه بإعداد ملف تعريف الارتباط. ويمكن أن تؤثر هذه القيمة على قيم المسار والنطاق التلقائيَين لملف تعريف الارتباط الذي تم إنشاؤه. وإذا لم يتم تحديد أذونات المضيف لعنوان URL هذا في ملف البيان، سيتعذّر تنفيذ طلب البيانات من واجهة برمجة التطبيقات.
-
القيمة
سلسلة اختيارية
قيمة ملف تعريف الارتباط. يكون هذا الحقل فارغًا تلقائيًا إذا تم حذفه.
-
-
معاودة الاتصال
الدالة اختيارية
تبدو معلَمة
callback
على النحو التالي:(cookie?: Cookie) => void
-
كعكة محلاة
ملف تعريف الارتباط اختياري
تحتوي على تفاصيل عن ملف تعريف الارتباط الذي تم ضبطه. وفي حال تعذّر الإعداد لأي سبب، ستكون القيمة "فارغة"، وسيتم ضبط
runtime.lastError
.
-
المرتجعات
-
Promise<Cookie | undefined>
Chrome 88 والإصدارات الأحدثلا تتوفّر الوعود إلا في الإصدار 3 من Manifest V3 والإصدارات الأحدث، وتحتاج الأنظمة الأساسية الأخرى إلى استخدام عمليات معاودة الاتصال.
فعاليات
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
يتم تنشيطها عند ضبط ملف تعريف ارتباط أو إزالته. في حالة خاصة، لاحظ أن تحديث خصائص ملف تعريف الارتباط يتم تنفيذه في عملية من خطوتين: تتم أولاً إزالة ملف تعريف الارتباط المراد تحديثه بالكامل، وإنشاء إشعار بعنوان "سبب" الاستبدال . وبعد ذلك، تتم كتابة ملف تعريف ارتباط جديد بالقيم المعدّلة، ما يؤدي إلى إنشاء إشعار ثانٍ يتضمّن كلمة "السبب" "فاضح".
المَعلمات
-
معاودة الاتصال
الوظيفة
تبدو معلَمة
callback
على النحو التالي:(changeInfo: object) => void
-
changeInfo
عنصر
-
cause
السبب الأساسي وراء تغيير ملف تعريف الارتباط.
-
كعكة محلاة
معلومات عن ملف تعريف الارتباط الذي تم ضبطه أو إزالته.
-
مُزالة
boolean
صحيح في حال إزالة ملف تعريف الارتباط.
-
-