browser.cookies

คำอธิบาย

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

สิทธิ์

cookies

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

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

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

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

โดยค่าเริ่มต้น เมธอด API ทั้งหมดจะทำงานกับคุกกี้ที่ไม่ได้แบ่งพาร์ติชัน คุณใช้พร็อพเพอร์ตี้ partitionKey เพื่อลบล้างลักษณะการทำงานนี้ได้

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

ตัวอย่าง

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

ประเภท

Cookie

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

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

• โดเมน

  สตริง

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

• expirationDate

  number ไม่บังคับ

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

• hostOnly

  บูลีน

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

• httpOnly

  บูลีน

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

• name

  สตริง

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

• partitionKey

  CookiePartitionKey ไม่บังคับ

  Chrome 119 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

• เส้นทาง

  สตริง

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

• sameSite

  SameSiteStatus

  Chrome 51 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

• ปลอดภัย

  บูลีน

  True หากคุกกี้มีการทำเครื่องหมายว่าปลอดภัย (เช่น ขอบเขตจำกัดเฉพาะช่องทางที่ปลอดภัย ซึ่งโดยปกติคือ HTTPS)

• เซสชัน

  บูลีน

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

• storeId

  สตริง

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

• value

  สตริง

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

CookieDetails

Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

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

• name

  สตริง

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

• partitionKey

  CookiePartitionKey ไม่บังคับ

  Chrome 119 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

• storeId

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

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

• URL

  สตริง

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

CookiePartitionKey

Chrome 119 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

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

• hasCrossSiteAncestor

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

  Chrome 130 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

• topLevelSite

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

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

CookieStore

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

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

• id

  สตริง

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

• tabIds

  number[]

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

FrameDetails

Chrome 132 ขึ้นไป browser.* ตั้งแต่ Chrome 148

รายละเอียดเพื่อระบุเฟรม

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

• documentId

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

  ตัวระบุที่ไม่ซ้ำกันสำหรับเอกสาร หากมีการระบุ frameId และ/หรือ tabId ระบบจะตรวจสอบความถูกต้องเพื่อให้ตรงกับเอกสารที่พบตามรหัสเอกสารที่ระบุ

• frameId

  number ไม่บังคับ

  ตัวระบุที่ไม่ซ้ำกันสำหรับเฟรมภายในแท็บ

• tabId

  number ไม่บังคับ

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

OnChangedCause

Chrome 44 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

ค่าแจกแจง

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 ขึ้นไป browser.* ตั้งแต่ Chrome 148

สถานะ "SameSite" ของคุกกี้ (https://tools.ietf.org/html/draft-west-first-party-cookies) "no_restriction" สอดคล้องกับคุกกี้ที่ตั้งค่าด้วย "SameSite=None", "lax" สอดคล้องกับ "SameSite=Lax" และ "strict" สอดคล้องกับ "SameSite=Strict" "unspecified" สอดคล้องกับชุดคุกกี้ที่ไม่มีแอตทริบิวต์ SameSite

ค่าแจกแจง

"no_restriction"

"lax"

"strict"

"unspecified"

เมธอด

get()

browser.cookies.get(
  details: CookieDetails,
): Promise<Cookie | undefined>

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

พารามิเตอร์

• รายละเอียด

  CookieDetails

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

• Promise<Cookie | undefined>

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

getAll()

browser.cookies.getAll(
  details: object,
): Promise<Cookie[]>

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

พารามิเตอร์

• รายละเอียด

  ออบเจ็กต์

  ข้อมูลสำหรับกรองคุกกี้ที่ดึงมา

  • โดเมน

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

    จำกัดคุกกี้ที่ดึงมาให้เป็นคุกกี้ที่มีโดเมนตรงกันหรือเป็นโดเมนย่อยของโดเมนนี้

  • name

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

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

  • partitionKey

    CookiePartitionKey ไม่บังคับ

    Chrome 119 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

  • เส้นทาง

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

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

  • ปลอดภัย

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

    กรองคุกกี้ตามพร็อพเพอร์ตี้ Secure

  • เซสชัน

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

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

  • storeId

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

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

  • URL

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

    จำกัดคุกกี้ที่ดึงมาให้เป็นคุกกี้ที่ตรงกับ URL ที่ระบุ

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

• Promise<Cookie[]>

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

getAllCookieStores()

browser.cookies.getAllCookieStores(): Promise<CookieStore[]>

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

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

• Promise<CookieStore[]>

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

getPartitionKey()

Chrome 132 ขึ้นไป browser.* ตั้งแต่ Chrome 148

browser.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

คีย์พาร์ติชันสำหรับเฟรมที่ระบุ

พารามิเตอร์

• รายละเอียด

  FrameDetails

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

• Promise<object>

remove()

browser.cookies.remove(
  details: CookieDetails,
): Promise<object | undefined>

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

พารามิเตอร์

• รายละเอียด

  CookieDetails

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

• Promise<object | undefined>

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

set()

browser.cookies.set(
  details: object,
): Promise<Cookie | undefined>

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

พารามิเตอร์

• รายละเอียด

  ออบเจ็กต์

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

  • โดเมน

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

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

  • expirationDate

    number ไม่บังคับ

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

  • httpOnly

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

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

  • name

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

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

  • partitionKey

    CookiePartitionKey ไม่บังคับ

    Chrome 119 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

  • เส้นทาง

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

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

  • sameSite

    SameSiteStatus ไม่บังคับ

    Chrome 51 ขึ้นไป browser.* ตั้งแต่ Chrome 148

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

  • ปลอดภัย

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

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

  • storeId

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

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

  • URL

    สตริง

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

  • value

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

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

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

• Promise<Cookie | undefined>

  Chrome 88 ขึ้นไป browser.* ตั้งแต่ Chrome 148

กิจกรรม

onChanged

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

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

พารามิเตอร์

• callback

  ฟังก์ชัน

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

  (changeInfo: object) => void

  • changeInfo

    ออบเจ็กต์

    • สาเหตุ

      OnChangedCause

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

    • คุกกี้

      Cookie

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

    • ลบแล้ว

      บูลีน

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