説明
chrome.cookies
API を使用して、Cookie のクエリと変更を行い、変更があったときに通知を受け取るようにします。
権限
cookies
Cookie API を使用するには、マニフェストで "cookies"
権限と、Cookie にアクセスしたいホストのホスト権限を宣言します。次に例を示します。
{
"name": "My extension",
...
"host_permissions": [
"*://*.google.com/"
],
"permissions": [
"cookies"
],
...
}
パーティショニング
パーティション化された Cookie を使用すると、サイトはトップレベル フレームの生成元に対する特定の Cookie をキーとして指定できます。たとえば、サイト A が iframe を使用してサイト B とサイト C に埋め込まれている場合、A のパーティション化された Cookie の埋め込みバージョンでは、B と C で異なる値が使用される可能性があります。
デフォルトでは、すべての API メソッドはパーティション分割されていない Cookie で動作します。partitionKey
プロパティを使用すると、この動作をオーバーライドできます。
拡張機能のパーティショニングの一般的な影響について詳しくは、ストレージと Cookie をご覧ください。
例
examples/api/cookies ディレクトリには、Cookies API の簡単な使用例があります。その他の例とソースコードの表示については、サンプルをご覧ください。
型
Cookie
HTTP Cookie に関する情報を表します。
プロパティ
-
ドメイン
string
Cookie のドメイン(「www.google.com」、「example.com」など)。
-
expirationDate
number(省略可)
Cookie の有効期限。UNIX エポック時刻からの経過秒数で表します。セッション Cookie では提供されません。
-
hostOnly
boolean
Cookie がホスト専用 Cookie の場合は true(つまり、リクエストのホストが Cookie のドメインと完全に一致する必要があります)。
-
httpOnly
boolean
Cookie が HttpOnly とマークされている場合は true(つまり、Cookie がクライアント側のスクリプトにアクセスできない場合)は true。
-
name
string
Cookie の名前。
-
partitionKeyChrome 119 以降
Partitioned 属性を使用して Cookie の読み取りまたは変更を行うためのパーティション キー。
-
パス
string
Cookie のパス。
-
sameSiteChrome 51 以降
Cookie の同一サイト ステータス(クロスサイト リクエストで Cookie が送信されたかどうか)です。
-
安全
boolean
Cookie が Secure としてマークされている場合は true(スコープが安全なチャネル(通常は HTTPS)に限定されます)。
-
セッション
boolean
有効期限のある永続的な Cookie ではなく、セッション Cookie の場合は true。
-
storeId
string
この Cookie が格納されている Cookie ストアの ID。getAllCookieStores() で提供されます。
-
value
string
Cookie の値。
CookieDetails
Cookie を識別する詳細。
プロパティ
-
name
string
アクセスする Cookie の名前。
-
partitionKeyChrome 119 以降
Partitioned 属性を使用して Cookie の読み取りまたは変更を行うためのパーティション キー。
-
storeId
string(省略可)
Cookie を検索する Cookie ストアの ID。デフォルトでは、現在の実行コンテキストの Cookie ストアが使用されます。
-
url
string
アクセスする Cookie が関連付けられている URL。この引数には完全な URL を指定できます。その場合、URL パスの後に続くデータ(クエリ文字列など)は無視されます。この URL のホスト権限がマニフェスト ファイルで指定されていない場合、API 呼び出しは失敗します。
CookiePartitionKey
パーティション化された Cookie のパーティション キーを表します。
プロパティ
-
topLevelSite
string(省略可)
パーティション化された Cookie を使用できる最上位のサイト。
CookieStore
ブラウザ内の Cookie ストアを表します。たとえば、シークレット モードのウィンドウは、シークレット モードではないウィンドウとは別の Cookie ストアを使用します。
プロパティ
-
id
string
Cookie ストアの一意の識別子。
-
tabIds
数値 []
この Cookie ストアを共有するすべてのブラウザタブの識別子。
OnChangedCause
Cookie が変更された根本的な原因です。Cookie が「chrome.cookies.remove」の明示的な呼び出しによって挿入または削除された場合、「cause」は「明示的」になります。Cookie が期限切れにより自動的に削除された場合、「cause」は「expired」になります。有効期限を過ぎた有効期限で上書きされたために Cookie が削除された場合、「cause」は「expired_overwrite」に設定されます。Cookie がガベージ コレクションによって自動的に削除された場合、「cause」は「強制排除」されます。「set」呼び出しで Cookie が上書きされ、自動的に削除された場合、「cause」は「overwrite」になります。状況に応じて対応を計画します。
列挙型
"expired_overwrite"
SameSiteStatus
Cookie の「SameSite」の状態(https://tools.ietf.org/html/draft-west-first-party-cookies)。「no_restriction」は「SameSite=None」、「lax」が「SameSite=Lax」、「strict」が「SameSite=Strict」に設定された Cookie に対応します。「unspecified」は、SameSite 属性なしで Cookie セットが設定されます。
列挙型
"no_restriction"
"lax"
"strict"
メソッド
get()
chrome.cookies.get(
details: CookieDetails,
callback?: function,
)
1 つの Cookie に関する情報を取得します。指定された URL に同じ名前の Cookie が複数ある場合は、パスが最も長い Cookie が返されます。同じパスの長さを持つ Cookie の場合は、作成時刻が最も早い Cookie が返されます。
パラメータ
戻り値
-
Promise<Cookie | undefined>
Chrome 88 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
getAll()
chrome.cookies.getAll(
details: object,
callback?: function,
)
指定した情報に一致するすべての Cookie を 1 つの Cookie ストアから取得します。返された Cookie は、パスが長い順に並べられます。パスの長さが同じ Cookie が複数ある場合は、作成日時が最も早い Cookie が最初に表示されます。このメソッドは、拡張機能がホスト権限を持っているドメインの Cookie のみを取得します。
パラメータ
-
詳細
オブジェクト
取得する Cookie をフィルタするための情報。
-
ドメイン
string(省略可)
取得された Cookie を、ドメインがこの Cookie と一致するか、サブドメインとなっているユーザーに限定します。
-
name
string(省略可)
Cookie を名前でフィルタします。
-
partitionKeyChrome 119 以降
Partitioned 属性を使用して Cookie の読み取りまたは変更を行うためのパーティション キー。
-
パス
string(省略可)
取得された Cookie を、パスがこの文字列と完全に一致するものに限定します。
-
安全
ブール値(省略可)
Secure プロパティで Cookie をフィルタします。
-
セッション
ブール値(省略可)
セッション Cookie と永続的な Cookie を除外します。
-
storeId
string(省略可)
Cookie の取得元の Cookie ストア。省略した場合は、現在の実行コンテキストの Cookie ストアが使用されます。
-
url
string(省略可)
取得した Cookie を、指定された URL に一致する Cookie に制限します。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。(cookies: Cookie[]) => void
-
Cookie
Cookie[]
指定した Cookie 情報と一致する、期限切れでない既存の Cookie すべて。
-
戻り値
-
Promise<Cookie[]>
Chrome 88 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
getAllCookieStores()
chrome.cookies.getAllCookieStores(
callback?: function,
)
既存のすべての Cookie ストアを一覧表示します。
パラメータ
-
callback
関数(省略可)
callback
パラメータは次のようになります。(cookieStores: CookieStore[]) => void
-
cookieStores
既存のすべての Cookie ストア。
-
戻り値
-
Promise<CookieStore[]>
Chrome 88 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
remove()
chrome.cookies.remove(
details: CookieDetails,
callback?: function,
)
名前を指定して Cookie を削除します。
パラメータ
-
callback
関数(省略可)
callback
パラメータは次のようになります。(details?: object) => void
-
詳細
オブジェクト 省略可
削除された Cookie の詳細が含まれます。なんらかの理由で削除できなかった場合は、「null」となり、
runtime.lastError
が設定されます。-
name
string
削除された Cookie の名前。
-
partitionKeyChrome 119 以降
Partitioned 属性を使用して Cookie の読み取りまたは変更を行うためのパーティション キー。
-
storeId
string
Cookie が削除された Cookie ストアの ID。
-
url
string
削除された Cookie に関連付けられている URL。
-
-
戻り値
-
Promise<object | undefined>
Chrome 88 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
set()
chrome.cookies.set(
details: object,
callback?: function,
)
指定した Cookie データで Cookie を設定します。同等の Cookie が存在する場合は、上書きする場合があります。
パラメータ
-
詳細
オブジェクト
設定されている Cookie に関する詳細。
-
ドメイン
string(省略可)
Cookie のドメイン。省略すると、Cookie はホスト専用 Cookie になります。
-
expirationDate
number(省略可)
Cookie の有効期限。UNIX エポック時刻からの経過秒数で表します。省略すると、Cookie はセッション Cookie になります。
-
httpOnly
ブール値(省略可)
Cookie を HttpOnly としてマークするかどうか。デフォルトは false です。
-
name
string(省略可)
Cookie の名前。省略した場合、デフォルトでは空になります。
-
partitionKeyChrome 119 以降
Partitioned 属性を使用して Cookie の読み取りまたは変更を行うためのパーティション キー。
-
パス
string(省略可)
Cookie のパス。デフォルトは、URL パラメータのパス部分です。
-
sameSite
SameSiteStatus 省略可
Chrome 51 以降Cookie の同一サイト ステータス。デフォルトは「unspecified」です。つまり、省略すると、Cookie は SameSite 属性を指定せずに設定されます。
-
安全
ブール値(省略可)
Cookie を Secure としてマークするかどうか。デフォルトは false です。
-
storeId
string(省略可)
Cookie を設定する Cookie ストアの ID。デフォルトでは、Cookie は現在の実行コンテキストの Cookie ストアに設定されます。
-
url
string
Cookie の設定に関連付けるリクエスト URI。この値は、作成される Cookie のデフォルトのドメインとパスの値に影響を与える可能性があります。この URL のホスト権限がマニフェスト ファイルで指定されていない場合、API 呼び出しは失敗します。
-
value
string(省略可)
Cookie の値。省略した場合、デフォルトでは空になります。
-
-
callback
関数(省略可)
callback
パラメータは次のようになります。(cookie?: Cookie) => void
-
Cookie
Cookie 省略可
設定されている Cookie の詳細が含まれます。なんらかの理由で設定が失敗した場合は、「null」となり、
runtime.lastError
が設定されます。
-
戻り値
-
Promise<Cookie | undefined>
Chrome 88 以降Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。
イベント
onChanged
chrome.cookies.onChanged.addListener(
callback: function,
)
Cookie が設定または削除されたときに呼び出されます。特例として、Cookie のプロパティの更新は 2 段階のプロセスとして実装されます。つまり、更新する Cookie はまず完全に削除され、「cause」(上書き)という通知が生成されます。その後、更新された値で新しい Cookie が書き込まれ、"cause" "露骨な" を含む 2 番目の通知が生成されます。
パラメータ
-
callback
機能
callback
パラメータは次のようになります。(changeInfo: object) => void
-
changeInfo
オブジェクト
-
cause
Cookie が変更された根本的な原因です。
-
Cookie
設定または削除された Cookie に関する情報。
-
削除済み
boolean
Cookie が削除された場合は true。
-
-