คำอธิบาย
ใช้ chrome.cookies
API เพื่อค้นหาและแก้ไขคุกกี้ รวมถึงรับการแจ้งเตือนเมื่อมีการเปลี่ยนแปลง
สิทธิ์
cookies
หากต้องการใช้ Cookies API ให้ประกาศสิทธิ์ "cookies"
ในไฟล์ Manifest พร้อมกับสิทธิ์ของโฮสต์สําหรับโฮสต์ที่คุณต้องการเข้าถึงคุกกี้ เช่น
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
การแบ่งพาร์ติชัน
คุกกี้ที่แบ่งพาร์ติชันช่วยให้เว็บไซต์ทำเครื่องหมายว่าควรใช้คีย์คุกกี้บางรายการกับต้นทางของเฟรมระดับบนสุด ซึ่งหมายความว่าหากเว็บไซต์ ก. ฝังโดยใช้ iframe ในเว็บไซต์ ข. และเว็บไซต์ ค. คุกกี้ที่มีการแบ่งพาร์ติชันจากเว็บไซต์ ก. ในเวอร์ชันที่ฝังอาจมีค่าแตกต่างกันในเว็บไซต์ ข. และ ค.
โดยค่าเริ่มต้น เมธอด API ทั้งหมดจะทํางานกับคุกกี้ที่ไม่ได้แบ่งพาร์ติชัน คุณใช้พร็อพเพอร์ตี้ partitionKey
เพื่อลบล้างลักษณะการทำงานนี้ได้
ดูรายละเอียดเกี่ยวกับผลกระทบทั่วไปของการแบ่งพาร์ติชันสำหรับส่วนขยายได้ที่หัวข้อพื้นที่เก็บข้อมูลและคุกกี้
ตัวอย่าง
คุณดูตัวอย่างง่ายๆ ของการใช้ cookies API ได้ในไดเรกทอรี examples/api/cookies ดูตัวอย่างอื่นๆ และความช่วยเหลือในการดูซอร์สโค้ดได้ที่ตัวอย่าง
ประเภท
Cookie
แสดงข้อมูลเกี่ยวกับคุกกี้ HTTP
พร็อพเพอร์ตี้
-
โดเมน
สตริง
โดเมนของคุกกี้ (เช่น "www.google.com", "example.com")
-
expirationDate
ตัวเลข ไม่บังคับ
วันที่หมดอายุของคุกกี้เป็นจำนวนวินาทีนับตั้งแต่ Epoch ของ UNIX ไม่มีให้สำหรับคุกกี้เซสชัน
-
hostOnly
บูลีน
จริงหากคุกกี้เป็นคุกกี้สำหรับโฮสต์เท่านั้น (เช่น โฮสต์ของคําขอต้องตรงกับโดเมนของคุกกี้ทุกประการ)
-
httpOnly
บูลีน
จริงหากมีการทําเครื่องหมายคุกกี้เป็น HttpOnly (กล่าวคือ สคริปต์ฝั่งไคลเอ็นต์ไม่สามารถเข้าถึงคุกกี้ได้)
-
ชื่อ
สตริง
ชื่อของคุกกี้
-
partitionKey
CookiePartitionKey ไม่บังคับ
Chrome 119 ขึ้นไปคีย์พาร์ติชันสําหรับการอ่านหรือแก้ไขคุกกี้ที่มีแอตทริบิวต์ "แบ่งพาร์ติชัน"
-
เส้นทาง
สตริง
เส้นทางของคุกกี้
-
sameSiteChrome 51 ขึ้นไป
สถานะ SameSite ของคุกกี้ (เช่น มีการส่งคุกกี้ไปกับคำขอข้ามเว็บไซต์หรือไม่)
-
รักษาความปลอดภัย
บูลีน
จริงหากมีการทําเครื่องหมายคุกกี้ว่าปลอดภัย (กล่าวคือ ขอบเขตของคุกกี้จํากัดอยู่ที่ช่องทางที่ปลอดภัย ซึ่งโดยทั่วไปคือ HTTPS)
-
เซสชัน
บูลีน
เป็นจริงหากคุกกี้เป็นคุกกี้เซสชัน ซึ่งต่างจากคุกกี้ถาวรที่มีวันที่หมดอายุ
-
storeId
สตริง
รหัสของที่เก็บคุกกี้ที่มีคุกกี้นี้ตามที่ระบุไว้ใน getAllCookieStores()
-
value
สตริง
ค่าของคุกกี้
CookieDetails
รายละเอียดเพื่อระบุคุกกี้
พร็อพเพอร์ตี้
-
ชื่อ
สตริง
ชื่อของคุกกี้ที่จะเข้าถึง
-
partitionKey
CookiePartitionKey ไม่บังคับ
Chrome 119 ขึ้นไปคีย์พาร์ติชันสําหรับการอ่านหรือแก้ไขคุกกี้ที่มีแอตทริบิวต์ "แบ่งพาร์ติชัน"
-
storeId
สตริง ไม่บังคับ
รหัสของที่เก็บคุกกี้ที่จะค้นหาคุกกี้ โดยค่าเริ่มต้น ระบบจะใช้ที่เก็บคุกกี้ของบริบทการเรียกใช้ปัจจุบัน
-
URL
สตริง
URL ที่เชื่อมโยงกับคุกกี้ที่จะเข้าถึง อาร์กิวเมนต์นี้อาจเป็น URL แบบเต็ม ซึ่งในกรณีนี้ ระบบจะไม่สนใจข้อมูลใดๆ ที่ตามหลังเส้นทาง URL (เช่น สตริงการค้นหา) หากไม่ได้ระบุสิทธิ์ของโฮสต์สําหรับ URL นี้ในไฟล์ Manifest การเรียก API จะดำเนินการไม่สำเร็จ
CookiePartitionKey
แสดงคีย์พาร์ติชันของคุกกี้ที่แบ่งพาร์ติชัน
พร็อพเพอร์ตี้
-
hasCrossSiteAncestor
บูลีน ไม่บังคับ
Chrome 130 ขึ้นไประบุว่ามีการตั้งค่าคุกกี้ในบริบทข้ามเว็บไซต์หรือไม่ ซึ่งจะป้องกันไม่ให้เว็บไซต์ระดับบนสุดที่ฝังอยู่ในบริบทข้ามเว็บไซต์เข้าถึงคุกกี้ที่ตั้งค่าโดยเว็บไซต์ระดับบนสุดในบริบทเว็บไซต์เดียวกัน
-
topLevelSite
สตริง ไม่บังคับ
เว็บไซต์ระดับบนสุดที่มีคุกกี้ที่แบ่งพาร์ติชัน
CookieStore
แสดงที่เก็บคุกกี้ในเบราว์เซอร์ ตัวอย่างเช่น หน้าต่างโหมดไม่ระบุตัวตนจะใช้ที่เก็บคุกกี้แยกต่างหากจากหน้าต่างที่ไม่ระบุตัวตน
พร็อพเพอร์ตี้
-
id
สตริง
ตัวระบุที่ไม่ซ้ำกันของที่เก็บคุกกี้
-
tabIds
number[]
ตัวระบุของแท็บเบราว์เซอร์ทั้งหมดที่ใช้พื้นที่เก็บคุกกี้นี้
FrameDetails
รายละเอียดเพื่อระบุเฟรม
พร็อพเพอร์ตี้
-
documentId
สตริง ไม่บังคับ
ตัวระบุที่ไม่ซ้ำกันของเอกสาร หากระบุ frameId และ/หรือ tabId ระบบจะตรวจสอบว่ารายการดังกล่าวตรงกับเอกสารที่พบตามรหัสเอกสารที่ระบุหรือไม่
-
frameId
ตัวเลข ไม่บังคับ
ตัวระบุที่ไม่ซ้ำกันของเฟรมภายในแท็บ
-
tabId
ตัวเลข ไม่บังคับ
ตัวระบุที่ไม่ซ้ำกันสำหรับแท็บที่มีเฟรม
OnChangedCause
เหตุผลที่ทําให้คุกกี้มีการเปลี่ยนแปลง หากมีการแทรกหรือนําคุกกี้ออกผ่านการเรียกใช้ "chrome.cookies.remove" อย่างชัดแจ้ง "cause" จะเป็น "explicit" หากระบบนำคุกกี้ออกโดยอัตโนมัติเนื่องจากหมดอายุ "สาเหตุ" จะแสดงเป็น "หมดอายุ" หากคุกกี้ถูกนําออกเนื่องจากมีการเขียนทับด้วยวันที่หมดอายุที่หมดอายุแล้ว ระบบจะตั้งค่า "cause" เป็น "expired_overwrite" หากคุกกี้ถูกนําออกโดยอัตโนมัติเนื่องจากการเก็บขยะ "สาเหตุ" จะ "ถูกนำออก" หากระบบนําคุกกี้ออกโดยอัตโนมัติเนื่องจากการเรียกใช้ "set" ที่เขียนทับคุกกี้ "cause" จะแสดงเป็น "overwrite" วางแผนการตอบกลับของคุณให้เหมาะสม
ค่าแจกแจง
"evicted"
"expired"
"explicit"
"expired_overwrite"
"overwrite"
SameSiteStatus
สถานะ "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 ที่ระบุ ระบบจะแสดงผลคุกกี้ที่มีเส้นทางยาวที่สุด สําหรับคุกกี้ที่มีความยาวเส้นทางเดียวกัน ระบบจะแสดงคุกกี้ที่มีเวลาสร้างเร็วที่สุด
พารามิเตอร์
การคืนสินค้า
-
Promise<Cookie | undefined>
Chrome 88 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่ก็มีคอลแบ็กไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
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 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่ก็มีคอลแบ็กไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
แสดงรายการที่เก็บคุกกี้ที่มีอยู่ทั้งหมด
พารามิเตอร์
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
จะมีลักษณะดังนี้(cookieStores: CookieStore[]) => void
-
cookieStores
คุกกี้ที่เก็บไว้ทั้งหมด
-
การคืนสินค้า
-
Promise<CookieStore[]>
Chrome 88 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่ก็มีคอลแบ็กไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
getPartitionKey()
chrome.cookies.getPartitionKey(
details: FrameDetails,
callback?: function,
)
คีย์พาร์ติชันของเฟรมที่ระบุ
พารามิเตอร์
-
รายละเอียด
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
จะมีลักษณะดังนี้(details: object) => void
-
รายละเอียด
ออบเจ็กต์
มีรายละเอียดเกี่ยวกับคีย์พาร์ติชันที่ดึงข้อมูล
-
partitionKey
คีย์พาร์ติชันสําหรับการอ่านหรือแก้ไขคุกกี้ที่มีแอตทริบิวต์ "แบ่งพาร์ติชัน"
-
-
การคืนสินค้า
-
Promise<object>
ไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่ก็มีคอลแบ็กไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
พารามิเตอร์
-
รายละเอียด
-
Callback
ฟังก์ชัน ไม่บังคับ
พารามิเตอร์
callback
จะมีลักษณะดังนี้(details?: object) => void
-
รายละเอียด
ออบเจ็กต์ ไม่บังคับ
มีรายละเอียดเกี่ยวกับคุกกี้ที่ถูกนําออก หากนำออกไม่สำเร็จไม่ว่าด้วยเหตุผลใดก็ตาม ค่านี้จะเท่ากับ "null" และระบบจะตั้งค่า
runtime.lastError
-
ชื่อ
สตริง
ชื่อของคุกกี้ที่ถูกนําออก
-
partitionKey
CookiePartitionKey ไม่บังคับ
Chrome 119 ขึ้นไปคีย์พาร์ติชันสําหรับการอ่านหรือแก้ไขคุกกี้ที่มีแอตทริบิวต์ "แบ่งพาร์ติชัน"
-
storeId
สตริง
รหัสของที่เก็บคุกกี้ที่นำคุกกี้ออก
-
URL
สตริง
URL ที่เชื่อมโยงกับคุกกี้ที่ถูกนําออก
-
-
การคืนสินค้า
-
Promise<object | undefined>
Chrome 88 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่ก็มีคอลแบ็กไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
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 ขึ้นไปไฟล์ Manifest เวอร์ชัน 3 ขึ้นไปรองรับ Promise แต่ก็มีคอลแบ็กไว้เพื่อให้ใช้กับเวอร์ชันก่อนหน้าได้ คุณใช้ทั้ง 2 รูปแบบในการเรียกใช้ฟังก์ชันเดียวกันไม่ได้ พรอมต์จะได้รับการแก้ไขด้วยประเภทเดียวกันกับที่ส่งไปยังการเรียกกลับ
กิจกรรม
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
เรียกใช้เมื่อมีการตั้งค่าหรือนําคุกกี้ออก ในกรณีพิเศษ โปรดทราบว่าการอัปเดตพร็อพเพอร์ตี้ของคุกกี้จะดำเนินการเป็น 2 ขั้นตอน โดยระบบจะนำคุกกี้ที่จะอัปเดตออกทั้งหมดก่อน จากนั้นจะสร้างการแจ้งเตือนที่มี "สาเหตุ" เป็น "เขียนทับ" หลังจากนั้น ระบบจะเขียนคุกกี้ใหม่โดยใช้ค่าที่อัปเดตแล้ว ซึ่งจะสร้างการแจ้งเตือนครั้งที่ 2 ที่มี "สาเหตุ" "explicit"
พารามิเตอร์
-
Callback
ฟังก์ชัน
พารามิเตอร์
callback
จะมีลักษณะดังนี้(changeInfo: object) => void
-
changeInfo
ออบเจ็กต์
-
สาเหตุ
เหตุผลที่ทําให้คุกกี้มีการเปลี่ยนแปลง
-
คุกกี้
ข้อมูลเกี่ยวกับคุกกี้ที่ตั้งค่าหรือนําออก
-
ลบแล้ว
บูลีน
เป็นจริงหากนําคุกกี้ออกแล้ว
-
-