chrome.cookies

คำอธิบาย

ใช้ chrome.cookies API เพื่อค้นหาและแก้ไขคุกกี้ รวมถึงรับการแจ้งเตือนเมื่อมีการเปลี่ยนแปลง

สิทธิ์

cookies

ไฟล์ Manifest

หากต้องการใช้ Cookies API คุณต้องประกาศสิทธิ์ "cookies" ในไฟล์ Manifest พร้อมกับสิทธิ์ของโฮสต์สําหรับโฮสต์ที่คุณต้องการเข้าถึงคุกกี้ เช่น

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

การแบ่งพาร์ติชัน

คุกกี้ที่แบ่งพาร์ติชันช่วยให้เว็บไซต์ทำเครื่องหมายว่าควรใช้คีย์คุกกี้บางอย่างกับต้นทางของเฟรมระดับบนสุด หมายความว่าหากเว็บไซต์ ก. ฝังอยู่โดยใช้ iframe ในเว็บไซต์ ข. และเว็บไซต์ C คุกกี้ที่แบ่งพาร์ติชันแล้วอาจมีค่าต่างกันในแต่ละเว็บไซต์

chrome.cookies ไม่รองรับการแบ่งพาร์ติชัน ซึ่งหมายความว่าเมธอดทั้งหมดจะอ่านและเขียนคุกกี้จากทุกพาร์ติชัน วิธี cookies.set() จะจัดเก็บคุกกี้ไว้ในพาร์ติชันเริ่มต้น

โปรดดูรายละเอียดเกี่ยวกับผลกระทบทั่วไปของการแบ่งพาร์ติชันสำหรับส่วนขยายที่หัวข้อพื้นที่เก็บข้อมูลและคุกกี้

ตัวอย่าง

คุณดูตัวอย่างง่ายๆ ของการใช้ cookies API ได้ในไดเรกทอรี examples/api/cookies ดูตัวอย่างอื่นๆ และความช่วยเหลือในการดูซอร์สโค้ดได้ที่ตัวอย่าง

ประเภท

Cookie

แสดงข้อมูลเกี่ยวกับคุกกี้ HTTP

พร็อพเพอร์ตี้

• โดเมน

  สตริง

  โดเมนของคุกกี้ (เช่น "www.google.com", "example.com")

• expirationDate

  หมายเลข ไม่บังคับ

  วันที่หมดอายุของคุกกี้เป็นจำนวนวินาทีนับตั้งแต่ UNIX Epoch ไม่ได้ระบุสำหรับคุกกี้ของเซสชัน

• hostOnly

  boolean

  จริงหากคุกกี้เป็นคุกกี้สำหรับโฮสต์เท่านั้น (เช่น โฮสต์ของคําขอต้องตรงกับโดเมนของคุกกี้ทุกประการ)

• httpOnly

  boolean

  เป็นจริงหากมีการทำเครื่องหมายคุกกี้เป็น HttpOnly (กล่าวคือ คุกกี้ไม่สามารถเข้าถึงได้จากสคริปต์ฝั่งไคลเอ็นต์)

• ชื่อ

  สตริง

  ชื่อของคุกกี้

• partitionKey

  CookiePartitionKey ไม่บังคับ

  Chrome 119 ขึ้นไป

  คีย์พาร์ติชันสําหรับการอ่านหรือแก้ไขคุกกี้ที่มีแอตทริบิวต์ "แบ่งพาร์ติชัน"

• เส้นทาง

  สตริง

  เส้นทางของคุกกี้

• sameSite

  SameSiteStatus

  Chrome 51 ขึ้นไป

  สถานะเว็บไซต์เดียวกันของคุกกี้ (เช่น คุกกี้ถูกส่งพร้อมกับคำขอข้ามเว็บไซต์หรือไม่)

• รักษาความปลอดภัย

  boolean

  จริงหากมีการทําเครื่องหมายคุกกี้ว่าปลอดภัย (กล่าวคือ ขอบเขตของคุกกี้จํากัดอยู่ที่ช่องทางที่ปลอดภัย ซึ่งโดยทั่วไปคือ HTTPS)

• เซสชัน

  boolean

  เป็นจริงหากคุกกี้เป็นคุกกี้เซสชัน ไม่ใช่คุกกี้ถาวรที่มีวันที่หมดอายุ

• storeId

  สตริง

  รหัสของที่เก็บคุกกี้ที่มีคุกกี้นี้ตามที่ระบุไว้ใน getAllCookieStores()

• value

  สตริง

  ค่าของคุกกี้

CookieDetails

Chrome 88 ขึ้นไป

รายละเอียดเพื่อระบุคุกกี้

พร็อพเพอร์ตี้

• ชื่อ

  สตริง

  ชื่อของคุกกี้ที่จะเข้าถึง

• partitionKey

  CookiePartitionKey ไม่บังคับ

  Chrome 119 ขึ้นไป

  คีย์พาร์ติชันสำหรับอ่านหรือแก้ไขคุกกี้ด้วยแอตทริบิวต์ที่มีการแบ่งพาร์ติชัน

• storeId

  สตริง ไม่บังคับ

  รหัสของที่เก็บคุกกี้ที่จะค้นหาคุกกี้ โดยค่าเริ่มต้น ระบบจะใช้ที่เก็บคุกกี้ของบริบทการดำเนินการปัจจุบัน

• URL

  สตริง

  URL ที่คุกกี้จะเข้าถึงมีการเชื่อมโยงกัน อาร์กิวเมนต์นี้อาจเป็น URL แบบเต็ม ซึ่งในกรณีนี้ ระบบจะไม่สนใจข้อมูลใดๆ ที่ตามหลังเส้นทาง URL (เช่น สตริงการค้นหา) หากไม่มีการระบุสิทธิ์ของโฮสต์สำหรับ URL นี้ในไฟล์ Manifest การเรียก API จะล้มเหลว

CookiePartitionKey

Chrome 119 ขึ้นไป

แสดงคีย์พาร์ติชันของคุกกี้ที่แบ่งพาร์ติชัน

พร็อพเพอร์ตี้

• hasCrossSiteAncestor

  บูลีน ไม่บังคับ

  Chrome 130 ขึ้นไป

  ระบุว่ามีการตั้งค่าคุกกี้ในบริบทแบบข้ามเว็บไซต์หรือไม่ ซึ่งจะป้องกันไม่ให้เว็บไซต์ระดับบนสุดที่ฝังอยู่ในบริบทข้ามเว็บไซต์เข้าถึงคุกกี้ที่ตั้งค่าโดยเว็บไซต์ระดับบนสุดในบริบทเว็บไซต์เดียวกัน

• topLevelSite

  สตริง ไม่บังคับ

  เว็บไซต์ระดับบนสุดที่มีคุกกี้ที่แบ่งพาร์ติชัน

CookieStore

แสดงที่เก็บคุกกี้ในเบราว์เซอร์ ตัวอย่างเช่น หน้าต่างโหมดไม่ระบุตัวตนจะใช้ที่เก็บคุกกี้แยกต่างหากจากหน้าต่างที่ไม่ใช่หน้าต่างที่ไม่ระบุตัวตน

พร็อพเพอร์ตี้

• id

  สตริง

  ตัวระบุที่ไม่ซ้ำกันสำหรับที่เก็บคุกกี้

• tabIds

  number[]

  ตัวระบุแท็บเบราว์เซอร์ทั้งหมดที่แชร์การจัดเก็บคุกกี้นี้

OnChangedCause

Chrome 44 ขึ้นไป

สาเหตุเบื้องหลังการเปลี่ยนแปลงคุกกี้ หากมีการแทรกหรือใช้คุกกี้ผ่านการเรียก "chrome.cookies.remove", "สาเหตุ" อย่างชัดเจน จะ "โจ่งแจ้ง อาจไม่เหมาะสม" หากคุกกี้ถูกนำออกโดยอัตโนมัติเนื่องจากหมดอายุ "สาเหตุ" จะ "หมดอายุ" หากคุกกี้ถูกนําออกเนื่องจากมีการเขียนทับด้วยวันที่หมดอายุที่หมดอายุแล้ว ระบบจะตั้งค่า "cause" เป็น "expired_overwrite" หากคุกกี้ถูกนําออกโดยอัตโนมัติเนื่องจากการเก็บขยะ "สาเหตุ" จะ "ถูกนำออก" หากระบบนําคุกกี้ออกโดยอัตโนมัติเนื่องจากการเรียกใช้ "set" ที่เขียนทับคุกกี้ "cause" จะแสดงเป็น "overwrite" โปรดวางแผนการตอบกลับตามความเหมาะสม

ค่าแจกแจง

"explicit"

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

ค่าแจกแจง

"lax"

"strict"

เมธอด

get()

สัญญา

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

ดึงข้อมูลเกี่ยวกับคุกกี้รายการเดียว หากมีคุกกี้ที่มีชื่อเดียวกันมากกว่า 1 รายการสําหรับ URL ที่ระบุ ระบบจะแสดงผลคุกกี้ที่มีเส้นทางยาวที่สุด สำหรับคุกกี้ที่มีความยาวเส้นทางเท่ากัน ระบบจะแสดงผลคุกกี้ที่มีเวลาที่สร้างเร็วที่สุด

พารามิเตอร์

• รายละเอียด

  CookieDetails

• Callback

  ไม่บังคับ

  พารามิเตอร์ callback มีลักษณะดังนี้

  (cookie?: Cookie) => void

  • คุกกี้

    คุกกี้ ไม่บังคับ

    มีรายละเอียดเกี่ยวกับคุกกี้ พารามิเตอร์นี้จะเป็น Null หากไม่พบคุกกี้ดังกล่าว

การคืนสินค้า

• สัญญา<คุกกี้ | ไม่ระบุ>

  Chrome เวอร์ชัน 88 ขึ้นไป

  ระบบรองรับ Promises สำหรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

getAll()

สัญญา

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

เรียกข้อมูลคุกกี้ทั้งหมดจากที่เก็บคุกกี้รายการเดียวที่ตรงกับข้อมูลที่ระบุ ระบบจะจัดเรียงคุกกี้ที่แสดงผล โดยเริ่มจากคุกกี้ที่มีเส้นทางยาวที่สุด หากคุกกี้หลายรายการมีความยาวเส้นทางเท่ากัน คุกกี้ที่มีเวลาสร้างเร็วที่สุดจะแสดงก่อน วิธีนี้จะดึงข้อมูลคุกกี้สำหรับโดเมนที่ส่วนขยายมีสิทธิ์โฮสต์เท่านั้น

พารามิเตอร์

• รายละเอียด

  ออบเจ็กต์

  ข้อมูลเพื่อกรองคุกกี้ที่ดึงมา

  • โดเมน

    สตริง ไม่บังคับ

    จำกัดคุกกี้ที่ดึงข้อมูลไว้เฉพาะคุกกี้ที่มีโดเมนตรงกันหรือเป็นโดเมนย่อยของโดเมนนี้

  • ชื่อ

    string ไม่บังคับ

    กรองคุกกี้ตามชื่อ

  • partitionKey

    CookiePartitionKey ไม่บังคับ

    Chrome 119 ขึ้นไป

    คีย์พาร์ติชันสำหรับอ่านหรือแก้ไขคุกกี้ด้วยแอตทริบิวต์ที่มีการแบ่งพาร์ติชัน

  • เส้นทาง

    string ไม่บังคับ

    จำกัดคุกกี้ที่เรียกมาต้องเป็นคุกกี้ที่มีเส้นทางตรงกับสตริงนี้ทุกประการ

  • รักษาความปลอดภัย

    บูลีน ไม่บังคับ

    กรองคุกกี้ตามพร็อพเพอร์ตี้ที่ปลอดภัย

  • เซสชัน

    บูลีน ไม่บังคับ

    กรองคุกกี้เซสชันกับคุกกี้ถาวรออก

  • storeId

    string ไม่บังคับ

    การจัดเก็บคุกกี้ที่ใช้เรียกดูคุกกี้ หากไม่ระบุ ระบบจะใช้ที่เก็บคุกกี้ของบริบทการดำเนินการปัจจุบัน

  • URL

    สตริง ไม่บังคับ

    จำกัดคุกกี้ที่ดึงข้อมูลไว้เฉพาะคุกกี้ที่ตรงกับ URL ที่ระบุ

• Callback

  ไม่บังคับ

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (cookies: Cookie[]) => void

  • คุกกี้

    คุกกี้[]

    คุกกี้ที่มีอยู่ทั้งหมดและยังไม่หมดอายุซึ่งตรงกับข้อมูลคุกกี้ที่ระบุ

การคืนสินค้า

• สัญญานะ<คุกกี้[]>

  Chrome 88 ขึ้นไป

  ระบบรองรับ Promises สำหรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

getAllCookieStores()

สัญญา

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

แสดงรายการที่เก็บคุกกี้ที่มีอยู่ทั้งหมด

พารามิเตอร์

• Callback

  ไม่บังคับ

  พารามิเตอร์ callback มีลักษณะดังนี้

  (cookieStores: CookieStore[]) => void

  • cookieStores

    CookieStore[]

    จัดเก็บคุกกี้ที่มีอยู่ทั้งหมด

การคืนสินค้า

• Promise&lt;CookieStore[]&gt;

  Chrome เวอร์ชัน 88 ขึ้นไป

  ระบบรองรับ Promises สำหรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้การเรียกกลับ

remove()

สัญญา

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

ลบคุกกี้ตามชื่อ

พารามิเตอร์

• รายละเอียด

  CookieDetails

• Callback

  ฟังก์ชัน ไม่บังคับ

  พารามิเตอร์ callback มีลักษณะดังนี้

  (details?: object) => void

  • รายละเอียด

    ออบเจ็กต์ไม่บังคับ

    มีรายละเอียดเกี่ยวกับคุกกี้ที่ถูกนําออก หากนำออกไม่สำเร็จไม่ว่าจะด้วยเหตุผลใดก็ตาม ค่านี้จะเป็น "null" และตั้งค่า runtime.lastError

    • ชื่อ

      สตริง

      ชื่อของคุกกี้ที่ถูกนําออก

    • partitionKey

      CookiePartitionKey ไม่บังคับ

      Chrome 119 ขึ้นไป

      คีย์พาร์ติชันสําหรับการอ่านหรือแก้ไขคุกกี้ที่มีแอตทริบิวต์ "แบ่งพาร์ติชัน"

    • storeId

      สตริง

      รหัสของที่เก็บคุกกี้ซึ่งคุกกี้ถูกนำออกไป

    • URL

      สตริง

      URL ที่เชื่อมโยงกับคุกกี้ที่ถูกนำออกแล้ว

การคืนสินค้า

• คำสัญญา<ออบเจ็กต์ | ไม่ระบุ>

  Chrome 88 ขึ้นไป

  Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

set()

สัญญา

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

ตั้งค่าคุกกี้ที่มีข้อมูลคุกกี้ที่ระบุ อาจเขียนทับคุกกี้ที่เทียบเท่ากัน (หากมี)

พารามิเตอร์

• รายละเอียด

  ออบเจ็กต์

  รายละเอียดเกี่ยวกับคุกกี้ที่ตั้งค่า

  • โดเมน

    สตริง ไม่บังคับ

    โดเมนของคุกกี้ หากไม่ระบุ คุกกี้จะกลายเป็นคุกกี้สำหรับโฮสต์เท่านั้น

  • expirationDate

    หมายเลข ไม่บังคับ

    วันที่หมดอายุของคุกกี้เป็นจำนวนวินาทีนับตั้งแต่ UNIX Epoch หากไม่ระบุ คุกกี้จะกลายเป็นคุกกี้ของเซสชัน

  • httpOnly

    บูลีน ไม่บังคับ

    ระบุว่าคุกกี้ควรทำเครื่องหมายเป็น HttpOnly หรือไม่ ค่าเริ่มต้นคือ False

  • ชื่อ

    string ไม่บังคับ

    ชื่อของคุกกี้ เว้นว่างไว้โดยค่าเริ่มต้นหากละเว้น

  • partitionKey

    CookiePartitionKey ไม่บังคับ

    Chrome 119 ขึ้นไป

    คีย์พาร์ติชันสําหรับการอ่านหรือแก้ไขคุกกี้ที่มีแอตทริบิวต์ "แบ่งพาร์ติชัน"

  • เส้นทาง

    string ไม่บังคับ

    เส้นทางของคุกกี้ ค่าเริ่มต้นคือส่วนเส้นทางของพารามิเตอร์ URL

  • sameSite

    SameSiteStatus ไม่บังคับ

    Chrome 51 ขึ้นไป

    สถานะเว็บไซต์เดียวกันของคุกกี้ ค่าเริ่มต้นคือ "unspecified" กล่าวคือ หากไม่ระบุ ระบบจะตั้งค่าคุกกี้โดยไม่ระบุแอตทริบิวต์ SameSite

  • รักษาความปลอดภัย

    บูลีน ไม่บังคับ

    ระบุว่าคุกกี้ปลอดภัยหรือไม่ ค่าเริ่มต้นคือ "เท็จ"

  • storeId

    string ไม่บังคับ

    รหัสของที่เก็บคุกกี้ที่จะตั้งค่าคุกกี้ โดยค่าเริ่มต้น ระบบจะตั้งค่าคุกกี้ไว้ในที่เก็บคุกกี้ของบริบทการดำเนินการปัจจุบัน

  • URL

    สตริง

    URI คำขอที่จะเชื่อมโยงกับการตั้งค่าคุกกี้ ค่านี้อาจส่งผลต่อค่าโดเมนและเส้นทางเริ่มต้นของคุกกี้ที่สร้างขึ้น หากไม่ได้ระบุสิทธิ์ของโฮสต์สําหรับ URL นี้ในไฟล์ Manifest การเรียก API จะดำเนินการไม่สำเร็จ

  • value

    string ไม่บังคับ

    ค่าของคุกกี้ ว่างเปล่าโดยค่าเริ่มต้นหากละไว้

• Callback

  ไม่บังคับ

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (cookie?: Cookie) => void

  • คุกกี้

    คุกกี้ ไม่บังคับ

    มีรายละเอียดเกี่ยวกับคุกกี้ที่ตั้งไว้ หากการตั้งค่าล้มเหลวไม่ว่าด้วยเหตุผลใดก็ตาม ค่านี้จะเป็น "null" และตั้งค่า runtime.lastError

การคืนสินค้า

• สัญญา<คุกกี้ | ไม่ระบุ>

  Chrome เวอร์ชัน 88 ขึ้นไป

  Promise รองรับไฟล์ Manifest V3 ขึ้นไปเท่านั้น ส่วนแพลตฟอร์มอื่นๆ ต้องใช้ Callback

กิจกรรม

onChanged

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

เรียกใช้เมื่อมีการตั้งค่าหรือนําคุกกี้ออก ในกรณีพิเศษ โปรดทราบว่าการอัปเดตพร็อพเพอร์ตี้ของคุกกี้จะดำเนินการเป็น 2 ขั้นตอน โดยระบบจะนำคุกกี้ที่จะอัปเดตออกทั้งหมดก่อน จากนั้นจะสร้างการแจ้งเตือนที่มี "สาเหตุ" เป็น "เขียนทับ" หลังจากนั้นจะมีการเขียนคุกกี้ใหม่ด้วยค่าที่อัปเดตแล้ว ทำให้เกิดการแจ้งเตือนครั้งที่ 2 พร้อมข้อความ "สาเหตุ" "อาจไม่เหมาะสม"

พารามิเตอร์

• Callback

  ฟังก์ชัน

  พารามิเตอร์ callback จะมีลักษณะดังนี้

  (changeInfo: object) => void

  • changeInfo

    ออบเจ็กต์

    • สาเหตุ

      OnChangedCause

      สาเหตุเบื้องหลังการเปลี่ยนแปลงคุกกี้

    • คุกกี้

      คุกกี้

      ข้อมูลเกี่ยวกับคุกกี้ที่ตั้งค่าหรือนําออก

    • ลบแล้ว

      boolean

      เป็นจริงหากมีการนำคุกกี้ออก