chrome.cookies

الوصف

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

الأذونات

cookies

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

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

التقسيم

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

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

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

أمثلة

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

الأنواع

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

أماكن إقامة

  • نطاق

    سلسلة

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

  • expirationDate

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

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

  • hostOnly

    boolean

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

  • httpOnly

    boolean

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

  • اسم

    سلسلة

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

  • partitionKey

    CookiePartitionKey اختياري

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

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

  • المسار

    سلسلة

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

  • sameSite

    SameSiteStatus

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

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

  • آمن

    boolean

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

  • جلسة

    boolean

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

  • storeId

    سلسلة

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

  • القيمة

    سلسلة

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

CookieDetails

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

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

أماكن إقامة

  • اسم

    سلسلة

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

  • partitionKey

    CookiePartitionKey اختياري

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

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

  • storeId

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

    رقم تعريف مخزن ملفات تعريف الارتباط حيث يتم البحث عن ملف تعريف الارتباط. وسيتم بشكل تلقائي استخدام مخزن ملفات تعريف الارتباط لسياق التنفيذ الحالي.

  • url

    سلسلة

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

CookiePartitionKey

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

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

أماكن إقامة

  • topLevelSite

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

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

CookieStore

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

أماكن إقامة

  • id

    سلسلة

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

  • tabIds

    الرقم[]

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

OnChangedCause

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

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

التعداد

SameSiteStatus

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

حالة "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 المحدّد، سيتم عرض الملف الذي يتضمّن أطول مسار. وبالنسبة إلى ملفات تعريف الارتباط التي لها طول المسار نفسه، سيتم عرض ملف تعريف الارتباط الذي له أقرب وقت للإنشاء.

المَعلمات

  • التفاصيل

    CookieDetails

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (cookie?: Cookie)=>void

    • كعكة محلاة

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

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

المرتجعات

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

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

    تتوفّر الوعود في إصدار 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 والإصدارات الأحدث

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

getAllCookieStores()

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

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

المَعلمات

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (cookieStores: CookieStore[])=>void

    • cookieStores

      CookieStore[]

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

المرتجعات

  • Promise<CookieStore[]>

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

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

remove()

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

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

المَعلمات

  • التفاصيل

    CookieDetails

  • معاودة الاتصال

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

    تبدو معلَمة callback على النحو التالي: 

    (details?: object)=>void

    • التفاصيل

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

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

      • اسم

        سلسلة

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

      • partitionKey

        CookiePartitionKey اختياري

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

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

      • storeId

        سلسلة

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

      • url

        سلسلة

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

المرتجعات

  • Promise<object|undefined>

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

    تتوفّر الوعود في إصدار 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.

المرتجعات

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

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

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

فعاليات

onChanged

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

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

المَعلمات

  • معاودة الاتصال

    الوظيفة

    تبدو معلَمة callback على النحو التالي: 

    (changeInfo: object)=>void

    • changeInfo

      كائن

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

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

      • مزال

        boolean

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