chrome.cookies

説明

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 の簡単な使用例があります。その他の例とソースコードの表示については、サンプルをご覧ください。

型

HTTP Cookie に関する情報を表します。

プロパティ

  • ドメイン

    文字列

    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

    文字列

    Cookie の名前。

  • partitionKey

    CookiePartitionKey 省略可

    Chrome 119 以降

    Partitioned 属性を使用して Cookie の読み取りまたは変更を行うためのパーティション キー。

  • パス

    文字列

    Cookie のパス。

  • sameSite

    SameSiteStatus

    Chrome 51 以降

    Cookie の同一サイト ステータス（クロスサイト リクエストで Cookie が送信されたかどうか）です。

  • 安全

    boolean

    Cookie が Secure としてマークされている場合は true（スコープが安全なチャネル（通常は HTTPS）に限定されます）。

  • session

    boolean

    有効期限のある永続的な Cookie ではなく、セッション Cookie の場合は true。

  • storeId

    文字列

    この Cookie が格納されている Cookie ストアの ID。getAllCookieStores() で提供されます。

  • value

    文字列

    Cookie の値。

CookieDetails

Chrome 88 以降

Cookie を識別する詳細。

プロパティ

  • name

    文字列

    アクセスする Cookie の名前。

  • partitionKey

    CookiePartitionKey 省略可

    Chrome 119 以降

    Partitioned 属性を使用して Cookie の読み取りまたは変更を行うためのパーティション キー。

  • storeId

    string（省略可）

    Cookie を検索する Cookie ストアの ID。デフォルトでは、現在の実行コンテキストの Cookie ストアが使用されます。

  • URL

    文字列

    アクセスする Cookie が関連付けられている URL。この引数には完全な URL を指定できます。その場合、URL パスの後に続くデータ（クエリ文字列など）は無視されます。この URL のホスト権限がマニフェスト ファイルで指定されていない場合、API 呼び出しは失敗します。

CookiePartitionKey

Chrome 119 以降

パーティション化された Cookie のパーティション キーを表します。

プロパティ

  • topLevelSite

    string（省略可）

    パーティション化された Cookie を使用できる最上位のサイト。

CookieStore

ブラウザ内の Cookie ストアを表します。たとえば、シークレット モードのウィンドウは、シークレット モードではないウィンドウとは別の Cookie ストアを使用します。

プロパティ

  • id

    文字列

    Cookie ストアの一意の識別子。

  • tabIds

    数値 []

    この Cookie ストアを共有するすべてのブラウザタブの識別子。

OnChangedCause

Chrome 44 以降

Cookie が変更された根本的な原因です。Cookie が「chrome.cookies.remove」の明示的な呼び出しによって挿入または削除された場合、「cause」は「明示的」になります。Cookie が期限切れにより自動的に削除された場合、「cause」は「expired」になります。有効期限を過ぎた有効期限で上書きされたために Cookie が削除された場合、「cause」は「expired_overwrite」に設定されます。Cookie がガベージ コレクションによって自動的に削除された場合、「cause」は「強制排除」されます。「set」呼び出しで Cookie が上書きされ、自動的に削除された場合、「cause」は「overwrite」になります。状況に応じて対応を計画します。

Enum

"expired_overwrite"

SameSiteStatus

Chrome 51 以降

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 セットが設定されます。

Enum

"no_restriction"

"lax"

"strict"

Methods

get()

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

1 つの Cookie に関する情報を取得します。指定された URL に同じ名前の Cookie が複数ある場合は、パスが最も長い Cookie が返されます。同じパスの長さを持つ Cookie の場合は、作成時刻が最も早い Cookie が返されます。

パラメータ

  • 詳細

    CookieDetails

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (cookie?: Cookie)=>void

    • Cookie

      Cookie 省略可

      Cookie の詳細が含まれます。該当する Cookie が見つからなかった場合、このパラメータは null になります。

戻り値

  • Promise<Cookie|未定義>

    Chrome 88 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

getAll()

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

指定した情報に一致するすべての Cookie を 1 つの Cookie ストアから取得します。返された Cookie は、パスが長い順に並べられます。パスの長さが同じ Cookie が複数ある場合は、作成日時が最も早い Cookie が最初に表示されます。このメソッドは、拡張機能がホスト権限を持っているドメインの Cookie のみを取得します。

パラメータ

  • 詳細

    オブジェクト

    取得する Cookie をフィルタするための情報。

    • ドメイン

      string（省略可）

      取得された Cookie を、ドメインがこの Cookie と一致するか、サブドメインとなっているユーザーに限定します。

    • name

      string（省略可）

      Cookie を名前でフィルタします。

    • partitionKey

      CookiePartitionKey 省略可

      Chrome 119 以降

      Partitioned 属性を使用して Cookie の読み取りまたは変更を行うためのパーティション キー。

    • パス

      string（省略可）

      取得された Cookie を、パスがこの文字列と完全に一致するものに限定します。

    • 安全

      ブール値（省略可）

      Secure プロパティで Cookie をフィルタします。

    • session

      ブール値（省略可）

      セッション 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()

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

既存のすべての Cookie ストアを一覧表示します。

パラメータ

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (cookieStores: CookieStore[])=>void

    • cookieStores

      CookieStore[]

      既存のすべての Cookie ストア。

戻り値

  • Promise<CookieStore[]>

    Chrome 88 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

remove()

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

名前を指定して Cookie を削除します。

パラメータ

  • 詳細

    CookieDetails

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (details?: object)=>void

    • 詳細

      オブジェクト 省略可

      削除された Cookie の詳細が含まれます。なんらかの理由で削除できなかった場合は、「null」となり、runtime.lastError が設定されます。

      • name

        文字列

        削除された Cookie の名前。

      • partitionKey

        CookiePartitionKey 省略可

        Chrome 119 以降

        Partitioned 属性を使用して Cookie の読み取りまたは変更を行うためのパーティション キー。

      • storeId

        文字列

        Cookie が削除された Cookie ストアの ID。

      • URL

        文字列

        削除された Cookie に関連付けられている URL。

戻り値

  • Promise<object|undefined>

    Chrome 88 以降

    Promise は Manifest V3 以降でサポートされていますが、コールバックは下位互換性のために提供されています。同じ関数呼び出しで両方を使用することはできません。Promise は、コールバックに渡されたのと同じ型で解決されます。

set()

Promise 
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 の名前。省略した場合、デフォルトでは空になります。

    • partitionKey

      CookiePartitionKey 省略可

      Chrome 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

      文字列

      Cookie の設定に関連付けるリクエスト URI。この値は、作成される Cookie のデフォルトのドメインとパスの値に影響を与える可能性があります。この URL のホスト権限がマニフェスト ファイルで指定されていない場合、API 呼び出しは失敗します。

    • value

      string（省略可）

      Cookie の値。省略した場合、デフォルトでは空になります。

  • callback

    関数（省略可）

    callback パラメータは次のようになります。 

    (cookie?: Cookie)=>void

    • Cookie

      Cookie 省略可

      設定されている Cookie の詳細が含まれます。なんらかの理由で設定が失敗した場合は、「null」となり、runtime.lastError が設定されます。

戻り値

  • Promise<Cookie|未定義>

    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

      オブジェクト

      • Cookie が変更された根本的な原因です。

      • Cookie

        Cookie

        設定または削除された Cookie に関する情報。

      • 削除

        boolean

        Cookie が削除された場合は true。