chrome.cookies

คำอธิบาย

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

สิทธิ์

cookies

ไฟล์ Manifest

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

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

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

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

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

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

ตัวอย่าง

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

ประเภท

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

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

  • โดเมน

    สตริง

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

  • expirationDate

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

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

  • hostOnly

    บูลีน

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

  • httpOnly

    บูลีน

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

  • ชื่อ

    สตริง

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

  • partitionKey

    CookiePartitionKey ไม่บังคับ

    Chrome 119 ขึ้นไป

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

  • เส้นทาง

    สตริง

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

  • sameSite

    SameSiteStatus

    Chrome 51 ขึ้นไป

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

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

    บูลีน

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

  • เซสชัน

    บูลีน

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

  • 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[]

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

FrameDetails

รอดำเนินการ

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

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

  • documentId

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

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

  • frameId

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

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

  • tabId

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

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

OnChangedCause

Chrome 44 ขึ้นไป

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

ค่าแจกแจง

"evicted"

"expired"

"explicit"

"expired_overwrite"

"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" "unspecified" สอดคล้องกับชุดคุกกี้ที่ไม่มีแอตทริบิวต์ SameSite

ค่าแจกแจง

"no_restriction"

"lax"

"strict"

"unspecified"

เมธอด

get()

สัญญา 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
)

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

พารามิเตอร์

  • รายละเอียด

    CookieDetails

  • Callback

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

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

    (cookie?: Cookie) => void

    • คุกกี้

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

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

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

  • Promise<Cookie | undefined>

    Chrome 88 ขึ้นไป

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

getAll()

สัญญา 
chrome.cookies.getAll(
  details: object,
  callback?: function,
)

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

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

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

    • โดเมน

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

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

    • ชื่อ

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

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

    • partitionKey

      CookiePartitionKey ไม่บังคับ

      Chrome 119 ขึ้นไป

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

    • เส้นทาง

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

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

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

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

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

    • เซสชัน

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

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

    • storeId

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

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

    • URL

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

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

  • Callback

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

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

    (cookies: Cookie[]) => void

    • คุกกี้

      Cookie[]

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

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

  • Promise<Cookie[]>

    Chrome 88 ขึ้นไป

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

getAllCookieStores()

สัญญา 
chrome.cookies.getAllCookieStores(
  callback?: function,
)

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

พารามิเตอร์

  • Callback

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

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

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      คุกกี้ที่เก็บไว้ทั้งหมด

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

  • Promise<CookieStore[]>

    Chrome 88 ขึ้นไป

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

getPartitionKey()

สัญญา รอดำเนินการ
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
)

คีย์พาร์ติชันของเฟรมที่ระบุ

พารามิเตอร์

  • รายละเอียด

    FrameDetails

  • Callback

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

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

    (details: object) => void

    • รายละเอียด

      ออบเจ็กต์

      มีรายละเอียดเกี่ยวกับคีย์พาร์ติชันที่ดึงข้อมูล

      • partitionKey

        CookiePartitionKey

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

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

  • Promise<object>

    ระบบรองรับ 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 ที่เชื่อมโยงกับคุกกี้ที่ถูกนําออก

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

  • Promise<object | undefined>

    Chrome 88 ขึ้นไป

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

set()

สัญญา 
chrome.cookies.set(
  details: object,
  callback?: function,
)

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

พารามิเตอร์

  • รายละเอียด

    ออบเจ็กต์

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

    • โดเมน

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

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

    • expirationDate

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

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

    • httpOnly

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

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

    • ชื่อ

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

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

    • partitionKey

      CookiePartitionKey ไม่บังคับ

      Chrome 119 ขึ้นไป

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

    • เส้นทาง

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

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

    • sameSite

      SameSiteStatus ไม่บังคับ

      Chrome 51 ขึ้นไป

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

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

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

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

    • storeId

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

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

    • URL

      สตริง

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

    • value

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

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

  • Callback

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

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

    (cookie?: Cookie) => void

    • คุกกี้

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

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

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

  • Promise<Cookie | undefined>

    Chrome 88 ขึ้นไป

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

กิจกรรม

onChanged

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

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

พารามิเตอร์

  • Callback

    ฟังก์ชัน

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

    (changeInfo: object) => void

    • changeInfo

      ออบเจ็กต์

      • สาเหตุ

        OnChangedCause

        เหตุผลที่ทําให้คุกกี้มีการเปลี่ยนแปลง

      • คุกกี้

        คุกกี้

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

      • ลบแล้ว

        บูลีน

        เป็นจริงหากนําคุกกี้ออกแล้ว