chrome.cookies

คำอธิบาย

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

สิทธิ์

cookies

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

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

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

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

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

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

ตัวอย่าง

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

ประเภท

Cookie

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

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

• โดเมน

  string

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

• expirationDate

  ตัวเลข ไม่บังคับ

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

• hostOnly

  boolean

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

• httpOnly

  boolean

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

• ชื่อ

  string

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

• partitionKey

  CookiePartitionKey ไม่บังคับ

  Chrome 119 ขึ้นไป

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

• เส้นทาง

  string

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

• sameSite

  SameSiteStatus

  Chrome 51 ขึ้นไป

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

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

  boolean

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

• เซสชัน

  boolean

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

• storeId

  string

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

• value

  string

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

CookieDetails

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

รายละเอียดที่จะระบุคุกกี้

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

• ชื่อ

  string

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

• partitionKey

  CookiePartitionKey ไม่บังคับ

  Chrome 119 ขึ้นไป

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

• storeId

  string ไม่บังคับ

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

• url

  string

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

CookiePartitionKey

Chrome 119 ขึ้นไป

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

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

• topLevelSite

  string ไม่บังคับ

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

CookieStore

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

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

• id

  string

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

• tabIds

  ตัวเลข[]

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

OnChangedCause

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"expired_overwrite"

SameSiteStatus

Chrome 51 ขึ้นไป

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

ค่าแจกแจง

"no_restriction"

"lax"

วิธีการ

get()

สัญญา

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

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

พารามิเตอร์

• รายละเอียด

  CookieDetails

• Callback

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

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

  (cookie?: Cookie)=>void

  • คุกกี้

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

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

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

• คำมั่นสัญญา<คุกกี้|undefined>

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

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getAll()

สัญญา

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

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

พารามิเตอร์

• รายละเอียด

  ออบเจ็กต์

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

  • โดเมน

    string ไม่บังคับ

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

  • ชื่อ

    string ไม่บังคับ

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

  • partitionKey

    CookiePartitionKey ไม่บังคับ

    Chrome 119 ขึ้นไป

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

  • เส้นทาง

    string ไม่บังคับ

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

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

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

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

  • เซสชัน

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

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

  • storeId

    string ไม่บังคับ

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

  • url

    string ไม่บังคับ

    จำกัดคุกกี้ที่ดึงมาเฉพาะคุกกี้ที่จะตรงกับ URL ที่ระบุ

• Callback

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

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

  (cookies: Cookie[])=>void

  • คุกกี้

    คุกกี้[]

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

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

• Promise<Cookie[]>

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

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

getAllCookieStores()

สัญญา

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

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

พารามิเตอร์

• Callback

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

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

  (cookieStores: CookieStore[])=>void

  • cookieStores

    CookieStore[]

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

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

• Promise<CookieStore[]>

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

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

remove()

สัญญา

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

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

พารามิเตอร์

• รายละเอียด

  CookieDetails

• Callback

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

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

  (details?: object)=>void

  • รายละเอียด

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

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

    • ชื่อ

      string

      ชื่อของคุกกี้ที่ถูกลบ

    • partitionKey

      CookiePartitionKey ไม่บังคับ

      Chrome 119 ขึ้นไป

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

    • storeId

      string

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

    • url

      string

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

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

• Promise<object|undefined>

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

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

set()

สัญญา

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

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

พารามิเตอร์

• รายละเอียด

  ออบเจ็กต์

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

  • โดเมน

    string ไม่บังคับ

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

  • expirationDate

    ตัวเลข ไม่บังคับ

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

  • httpOnly

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

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

  • ชื่อ

    string ไม่บังคับ

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

  • partitionKey

    CookiePartitionKey ไม่บังคับ

    Chrome 119 ขึ้นไป

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

  • เส้นทาง

    string ไม่บังคับ

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

  • sameSite

    SameSiteStatus ไม่บังคับ

    Chrome 51 ขึ้นไป

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

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

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

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

  • storeId

    string ไม่บังคับ

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

  • url

    string

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

  • value

    string ไม่บังคับ

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

• Callback

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

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

  (cookie?: Cookie)=>void

  • คุกกี้

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

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

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

• คำมั่นสัญญา<คุกกี้|undefined>

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

  Manifest V3 ขึ้นไปรองรับคำสัญญา แต่จะใช้โค้ดเรียกกลับเพื่อความเข้ากันได้แบบย้อนหลัง คุณไม่สามารถใช้ทั้ง 2 ฟีเจอร์ในการเรียกใช้ฟังก์ชันเดียวกันได้ คำสัญญาจะยุติด้วยประเภทเดียวกันกับที่ส่งไปยังโค้ดเรียกกลับ

กิจกรรม

onChanged

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

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

พารามิเตอร์

• Callback

  ฟังก์ชัน

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

  (changeInfo: object)=>void

  • changeInfo

    ออบเจ็กต์

    • cause

      OnChangedCause

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

    • คุกกี้

      คุกกี้

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

    • ถูกลบทิ้ง

      boolean

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