Opis
Interfejs API chrome.cookies
pozwala na wysyłanie zapytań i modyfikowanie plików cookie oraz otrzymywanie powiadomień o zmianach.
Uprawnienia
cookies
Aby korzystać z interfejsu cookie API, zadeklaruj w pliku manifestu uprawnienia "cookies"
oraz uprawnienia hosta dla wszystkich hostów, do których pliki cookie chcesz mieć dostęp. Na przykład:
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
Partycjonowanie
Partycjonowane pliki cookie umożliwiają witrynie oznaczenie niektórych plików cookie jako klucza dostępu do źródła ramki najwyższego poziomu. Oznacza to, że jeśli na przykład witryna A jest umieszczona w witrynie B i w witrynie C przy użyciu elementu iframe, wersje umieszczonego w witrynie podzielonego pliku cookie pochodzącego z witryny A mogą mieć różne wartości w witrynach B i C.
Domyślnie wszystkie metody interfejsu API działają na niepartycjonowanych plikach cookie. Aby zastąpić to działanie, możesz użyć właściwości partitionKey
.
Szczegółowe informacje na temat ogólnego wpływu partycjonowania rozszerzeń znajdziesz w sekcji Pamięć i pliki cookie.
Przykłady
Prosty przykład interfejsu API plików cookie znajdziesz w katalogu examples/api/cookies. Więcej przykładów oraz pomoc dotyczącą wyświetlania kodu źródłowego znajdziesz w sekcji Przykłady.
Typy
Cookie
Reprezentuje informacje o pliku cookie HTTP.
Właściwości
-
domena
string,
Domena pliku cookie (np. „www.google.com”, „example.com”).
-
expirationDate
Liczba opcjonalnie
Data ważności pliku cookie jako liczba sekund od początku epoki UNIX. Niewykorzystywane w przypadku plików cookie sesji.
-
hostOnly
boolean
Wartość to „prawda”, jeśli plik cookie jest tylko hostem (tzn. host żądania musi dokładnie odpowiadać domenie pliku cookie).
-
httpOnly
boolean
Prawda, jeśli plik cookie jest oznaczony jako HttpOnly (tzn. plik cookie jest niedostępny dla skryptów po stronie klienta).
-
nazwa
string,
Nazwa pliku cookie.
-
partitionKey
CookiePartitionKey opcjonalny
Chrome 119 i nowsze wersjeKlucz partycji umożliwiający odczytywanie lub modyfikowanie plików cookie z atrybutem Partycjonowanie.
-
ścieżka
string,
Ścieżka pliku cookie.
-
sameSiteChrome 51 i nowsze wersje
Stan pliku cookie w tej samej witrynie (np. czy plik cookie jest wysyłany w ramach żądań z innych witryn).
-
Bezpieczny
boolean
Wartość to „prawda”, jeśli plik cookie jest oznaczony jako bezpieczny (tzn. jego zakres jest ograniczony do bezpiecznych kanałów, zwykle HTTPS).
-
sesja
boolean
Prawda, jeśli plik cookie jest plikiem cookie sesji, a nie trwałym plikiem cookie z datą ważności.
-
storeId
string,
Identyfikator magazynu plików cookie zawierającego ten plik cookie podany w metodzie getAllCookieStores().
-
value
string,
Wartość pliku cookie.
CookieDetails
Szczegóły identyfikujące plik cookie.
Właściwości
-
nazwa
string,
Nazwa pliku cookie, do którego chcesz uzyskać dostęp.
-
partitionKey
CookiePartitionKey opcjonalny
Chrome 119 i nowsze wersjeKlucz partycji umożliwiający odczytywanie lub modyfikowanie plików cookie z atrybutem Partycjonowanie.
-
storeId
ciąg znaków opcjonalny
Identyfikator magazynu plików cookie, w którym ma być szukany plik cookie. Domyślnie używany jest magazyn plików cookie bieżącego kontekstu wykonywania.
-
URL
string,
Adres URL, z którym jest powiązany plik cookie, z którym można uzyskać dostęp. Ten argument może być pełnym adresem URL.W takim przypadku wszelkie dane występujące po ścieżce adresu URL (np. ciąg zapytania) są po prostu ignorowane. Jeśli uprawnienia hosta dla tego adresu URL nie są określone w pliku manifestu, wywołanie interfejsu API się nie uda.
CookiePartitionKey
Reprezentuje klucz partycji pliku cookie z podzielonym plikiem cookie.
Właściwości
-
topLevelSite
ciąg znaków opcjonalny
Witryna najwyższego poziomu, w której dostępny jest podzielony plik cookie.
CookieStore
Reprezentuje magazyn plików cookie w przeglądarce. Na przykład w oknie trybu incognito znajduje się inny magazyn plików cookie niż okno trybu normalnego.
Właściwości
-
id
string,
Unikalny identyfikator magazynu plików cookie.
-
tabIds
liczba[]
Identyfikatory wszystkich kart przeglądarki, które korzystają z tego magazynu plików cookie.
OnChangedCause
Przyczyna zmiany pliku cookie. Jeśli plik cookie został wstawiony lub usunięty przez jawne wywołanie „chrome.cookies.remove”, „powodem” będzie „dla pełnoletnich”. Jeśli plik cookie został automatycznie usunięty z powodu wygaśnięcia ważności, atrybut „powod” ma wartość „wygasł”. Jeśli plik cookie został usunięty z powodu zastąpienia jego datą ważności, która już wygasła, atrybut „cause” będzie miał wartość „expired_overwrite”. Jeśli plik cookie został automatycznie usunięty z powodu czyszczenia pamięci, parametr „cause” będzie miał wartość „wykluczone”. Jeśli plik cookie został automatycznie usunięty z powodu wywołania „set”, które go zastąpiło, „powod” to „zastąp”. Weź to pod uwagę, planując swoją odpowiedź.
Typ wyliczeniowy
"expired_overwrite"
SameSiteStatus
Stan „SameSite” pliku cookie (https://tools.ietf.org/html/draft-west-first-party-cookies). Parametr „no_restriction” odpowiada ustawieniu „SameSite=None”, „lax” dotyczące „SameSite=Lax” i „strict” do „SameSite=Strict”. Wartość „nieokreślony” odpowiada zestawowi plików cookie bez atrybutu SameSite.
Typ wyliczeniowy
"no_restriction"
"lax"
Metody
get()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
)
Pobiera informacje o pojedynczym pliku cookie. Jeśli pod danym adresem URL istnieje więcej niż 1 plik cookie o tej samej nazwie, zwracany jest ten o najdłuższej ścieżce. W przypadku plików cookie o tej samej długości ścieżki zwracany jest plik z najwcześniejszym czasem utworzenia.
Parametry
-
szczegóły
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(cookie?: Cookie) => void
-
ciastko
Plik cookie opcjonalnie
Zawiera szczegółowe informacje o pliku cookie. Jeśli nie znaleziono takiego pliku cookie, parametr ma wartość null.
-
Zwroty
-
Promise<Cookie | undefined>
Chrome 88 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
Pobiera wszystkie pliki cookie z jednego magazynu plików cookie, które pasują do podanych informacji. Zwrócone pliki cookie zostaną posortowane, zaczynając od tych o najdłuższej ścieżce. Jeśli wiele plików cookie ma taką samą długość ścieżki, jako pierwsze pojawią się pliki, które wykonano najwcześniej. Ta metoda pobiera pliki cookie tylko z domen, do których rozszerzenie ma uprawnienia hosta.
Parametry
-
szczegóły
obiekt
Informacje służące do filtrowania pobieranych plików cookie.
-
domena
ciąg znaków opcjonalny
Ogranicza pobieranie plików cookie do tych, których domeny pasują do tej domeny lub są jej subdomenami.
-
nazwa
ciąg znaków opcjonalny
Filtruje pliki cookie według nazwy.
-
partitionKey
CookiePartitionKey opcjonalny
Chrome 119 i nowsze wersjeKlucz partycji umożliwiający odczytywanie lub modyfikowanie plików cookie z atrybutem Partycjonowanie.
-
ścieżka
ciąg znaków opcjonalny
Ogranicza pobrane pliki cookie do tych, których ścieżka ściśle pasuje do tego ciągu.
-
Bezpieczny
wartość logiczna opcjonalna
Filtruje pliki cookie według właściwości „Secure”.
-
sesja
wartość logiczna opcjonalna
Odfiltrowuje pliki cookie sesji i trwałe pliki cookie.
-
storeId
ciąg znaków opcjonalny
Magazyn plików cookie, z którego mają być pobierane pliki cookie. Jeśli nazwa zostanie pominięta, używany będzie magazyn plików cookie bieżącego kontekstu wykonywania.
-
URL
ciąg znaków opcjonalny
Ogranicza pobrane pliki cookie do tych, które pasują do podanego adresu URL.
-
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(cookies: Cookie[]) => void
-
ciastka
Wszystkie istniejące i aktualne pliki cookie, które pasują do podanych informacji o plikach cookie.
-
Zwroty
-
Promise<Cookie[]>
Chrome 88 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
Wyświetla listę wszystkich istniejących magazynów plików cookie.
Parametry
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(cookieStores: CookieStore[]) => void
-
cookieStores
Wszystkie dotychczasowe magazyny plików cookie.
-
Zwroty
-
Promise<CookieStore[]>
Chrome 88 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
remove()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
)
Usuwa plik cookie według nazwy.
Parametry
-
szczegóły
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(details?: object) => void
-
szczegóły
obiekt opcjonalnie
Zawiera szczegółowe informacje o usuniętym pliku cookie. Jeśli z jakiegoś powodu usunięcie nie uda się usunąć, ta wartość będzie mieć wartość „null”, a wartość
runtime.lastError
zostanie ustawiona.-
nazwa
string,
Nazwa usuniętego pliku cookie.
-
partitionKey
CookiePartitionKey opcjonalny
Chrome 119 i nowsze wersjeKlucz partycji umożliwiający odczytywanie lub modyfikowanie plików cookie z atrybutem Partycjonowanie.
-
storeId
string,
Identyfikator magazynu plików cookie, z którego został usunięty plik cookie.
-
URL
string,
Adres URL powiązany z usuniętym plikiem cookie.
-
-
Zwroty
-
Promise<object | undefined>
Chrome 88 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
set()
chrome.cookies.set(
details: object,
callback?: function,
)
Ustawianie pliku cookie z podanymi danymi z pliku cookie. Może zastąpić odpowiadające mu pliki cookie, jeśli istnieją.
Parametry
-
szczegóły
obiekt
Szczegółowe informacje o ustawionym pliku cookie.
-
domena
ciąg znaków opcjonalny
Domena pliku cookie. W przypadku pominięcia tego parametru plik cookie stanie się plikiem cookie wyłącznie na poziomie hosta.
-
expirationDate
Liczba opcjonalnie
Data ważności pliku cookie jako liczba sekund od początku epoki UNIX. W przypadku jego pominięcia plik cookie staje się plikiem cookie sesji.
-
httpOnly
wartość logiczna opcjonalna
Określa, czy plik cookie ma być oznaczony jako HttpOnly. Wartość domyślna to fałsz.
-
nazwa
ciąg znaków opcjonalny
Nazwa pliku cookie. Jeśli zostanie pominięty, pole domyślnie puste.
-
partitionKey
CookiePartitionKey opcjonalny
Chrome 119 i nowsze wersjeKlucz partycji umożliwiający odczytywanie lub modyfikowanie plików cookie z atrybutem Partycjonowanie.
-
ścieżka
ciąg znaków opcjonalny
Ścieżka pliku cookie. Domyślnie jest to ścieżka parametru adresu URL.
-
sameSite
SameSiteStatus – opcjonalny
Chrome 51 i nowsze wersjeStan pliku cookie w tej samej witrynie. Wartość domyślna to „nieokreślony”, co oznacza, że jeśli zostanie pominięty, plik cookie zostanie ustawiony bez określania atrybutu SameSite.
-
Bezpieczny
wartość logiczna opcjonalna
Określa, czy plik cookie ma być oznaczony jako bezpieczny. Wartość domyślna to fałsz.
-
storeId
ciąg znaków opcjonalny
Identyfikator magazynu plików cookie, w którym ma zostać ustawiony plik cookie. Domyślnie plik cookie jest umieszczony w magazynie plików cookie bieżącego kontekstu wykonywania.
-
URL
string,
Identyfikator URI żądania powiązany z ustawieniem pliku cookie. Ta wartość może mieć wpływ na domyślne wartości domeny i ścieżek tworzonego pliku cookie. Jeśli uprawnienia hosta dla tego adresu URL nie są określone w pliku manifestu, wywołanie interfejsu API się nie uda.
-
value
ciąg znaków opcjonalny
Wartość pliku cookie. Jeśli zostanie pominięty, pole domyślnie puste.
-
-
wywołanie zwrotne
funkcja opcjonalnie
Parametr
callback
wygląda tak:(cookie?: Cookie) => void
-
ciastko
Plik cookie opcjonalnie
Zawiera szczegółowe informacje o ustawionym pliku cookie. Jeśli z jakiegoś powodu ustawienie nie powiedzie się, wartość będzie miała wartość „null”, a wartość
runtime.lastError
zostanie ustawiona.
-
Zwroty
-
Promise<Cookie | undefined>
Chrome 88 i nowsze wersjeObietnice są obsługiwane w platformie Manifest V3 i nowszych, ale wywołania zwrotne są dostępne na potrzeby zgodności wstecznej. Nie można użyć obu w tym samym wywołaniu funkcji. Obietnica znika z tym samym typem, który jest przekazywany do wywołania zwrotnego.
Wydarzenia
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
Uruchamiane, gdy plik cookie jest ustawiony lub usunięty. W szczególnym przypadku aktualizowanie właściwości pliku cookie jest procesem dwuetapowym: plik cookie przeznaczony do aktualizacji jest najpierw całkowicie usuwany, co powoduje wygenerowanie powiadomienia o treści „przyczyna” „zastąp” . Następnie zapisywany jest nowy plik cookie ze zaktualizowanymi wartościami, generując drugie powiadomienie z wartością „cause” „explicit”.
Parametry
-
wywołanie zwrotne
funkcja
Parametr
callback
wygląda tak:(changeInfo: object) => void
-
changeInfo
obiekt
-
cause
Przyczyna zmiany pliku cookie.
-
ciastko
Informacje o ustawionym lub usuniętym pliku cookie.
-
usunięta
boolean
Prawda, jeśli plik cookie został usunięty.
-
-