browser.cookies

説明

chrome.cookies API を使用して、Cookie のクエリと変更を行い、Cookie が変更されたときに通知を受け取ります。

権限

cookies

Cookies 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 をご覧ください。

例

cookies API の簡単な使用例については、examples/api/cookies ディレクトリをご覧ください。その他の例とソースコードの表示方法については、サンプルをご覧ください。

型

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

プロパティ

  • ドメイン

    文字列

    Cookie のドメイン（例: 「www.google.com」、「example.com」）。

  • expirationDate

    number 省略可

    UNIX エポックからの秒数で表した Cookie の有効期限。セッション Cookie には指定されません。

  • hostOnly

    ブール値

    Cookie がホスト専用 Cookie の場合は true（つまり、リクエストのホストが Cookie のドメインと完全に一致する必要があります）。

  • httpOnly

    ブール値

    Cookie が HttpOnly としてマークされている場合（つまり、Cookie がクライアントサイド スクリプトにアクセスできない場合）は true。

  • name

    文字列

    Cookie の名前。

  • partitionKey

    CookiePartitionKey 省略可

    Chrome 119 以降 Chrome 148 以降の browser.*

    Partitioned 属性を持つ Cookie の読み取りまたは変更に使用するパーティション キー。

  • パス

    文字列

    Cookie のパス。

  • sameSite

    SameSiteStatus

    Chrome 51 以降 Chrome 148 以降の browser.*

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

  • 安全

    ブール値

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

  • セッション

    ブール値

    Cookie がセッション Cookie の場合は true。有効期限のある永続 Cookie の場合は false。

  • storeId

    文字列

    getAllCookieStores() で提供される、この Cookie を含む Cookie ストアの ID。

  • 値

    文字列

    Cookie の値。

CookieDetails

Chrome 88 以降 Chrome 148 以降の browser.*

Cookie を識別するための詳細。

プロパティ

  • name

    文字列

    アクセスする Cookie の名前。

  • partitionKey

    CookiePartitionKey 省略可

    Chrome 119 以降 Chrome 148 以降の browser.*

    Partitioned 属性を持つ Cookie の読み取りまたは変更に使用するパーティション キー。

  • storeId

    文字列 省略可

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

  • URL

    文字列

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

CookiePartitionKey

Chrome 119 以降 Chrome 148 以降の browser.*

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

プロパティ

  • hasCrossSiteAncestor

    boolean 省略可

    Chrome 130 以降 Chrome 148 以降の browser.*

    Cookie がクロスサイト コンテキストで設定されたかどうかを示します。これにより、クロスサイト コンテキストに埋め込まれたトップレベル サイトが、同じサイト コンテキストでトップレベル サイトによって設定された Cookie にアクセスできなくなります。

  • topLevelSite

    文字列 省略可

    パーティション化された Cookie を使用できるトップレベル サイト。

CookieStore

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

プロパティ

  • id

    文字列

    Cookie ストアの固有識別子。

  • tabIds

    number[]

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

FrameDetails

Chrome 132 以降 Chrome 148 以降の browser.*

フレームを識別するための詳細。

プロパティ

  • documentId

    文字列 省略可

    ドキュメントの固有識別子。frameId や tabId が指定されている場合は、指定されたドキュメント ID で見つかったドキュメントと一致するかどうかが検証されます。

  • frameId

    number 省略可

    タブ内のフレームの固有識別子。

  • tabId

    number 省略可

    フレームを含むタブの固有識別子。

OnChangedCause

Chrome 44 以降 Chrome 148 以降の browser.*

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

列挙型

「evicted」

「期限切れ」

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 以降 Chrome 148 以降の browser.*

Cookie の「SameSite」状態（https://tools.ietf.org/html/draft-west-first-party-cookies）。「no_restriction」は「SameSite=None」に設定された Cookie に対応し、「lax」は「SameSite=Lax」に、「strict」は「SameSite=Strict」に対応します。「unspecified」は、SameSite 属性なしで設定された Cookie に対応します。

列挙型

"no_restriction"

"lax"

"strict"

"unspecified"

メソッド

get()

browser.cookies.get(
  details: CookieDetails,
): Promise<Cookie | undefined>

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

パラメータ

戻り値

  • Promise<Cookie | undefined>

    Chrome 88 以降 Chrome 148 以降の browser.*

getAll()

browser.cookies.getAll(
  details: object,
): Promise<Cookie[]>

指定された情報に一致するすべての Cookie を 1 つの Cookie ストレージから取得します。返される Cookie は、パスが最も長いものが最初にくるように並べ替えられます。複数の Cookie のパスの長さが同じ場合は、作成時間が最も早い Cookie が最初になります。このメソッドは、拡張機能がホスト権限を持つドメインの Cookie のみを取得します。

パラメータ

  • 詳細

    オブジェクト

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

    • ドメイン

      文字列 省略可

      取得する Cookie を、ドメインがこのドメインと一致するもの、またはこのドメインのサブドメインであるものに制限します。

    • name

      文字列 省略可

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

    • partitionKey

      CookiePartitionKey 省略可

      Chrome 119 以降 Chrome 148 以降の browser.*

      Partitioned 属性を持つ Cookie の読み取りまたは変更に使用するパーティション キー。

    • パス

      文字列 省略可

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

    • 安全

      boolean 省略可

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

    • セッション

      boolean 省略可

      セッション Cookie と永続 Cookie をフィルタします。

    • storeId

      文字列 省略可

      Cookie を取得する Cookie ストア。省略すると、現在の実行コンテキストの Cookie ストアが使用されます。

    • URL

      文字列 省略可

      取得する Cookie を、指定された URL に一致するものに制限します。

戻り値

  • Promise<Cookie[]>

    Chrome 88 以降 Chrome 148 以降の browser.*

getAllCookieStores()

browser.cookies.getAllCookieStores(): Promise<CookieStore[]>

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

戻り値

  • Promise<CookieStore[]>

    Chrome 88 以降 Chrome 148 以降の browser.*

getPartitionKey()

Chrome 132 以降 Chrome 148 以降の browser.* 
browser.cookies.getPartitionKey(
  details: FrameDetails,
): Promise<object>

指定されたフレームのパーティション キー。

パラメータ

戻り値

  • Promise<object>

remove()

browser.cookies.remove(
  details: CookieDetails,
): Promise<object | undefined>

Cookie を名前で削除します。

パラメータ

戻り値

  • Promise<object | undefined>

    Chrome 88 以降 Chrome 148 以降の browser.*

set()

browser.cookies.set(
  details: object,
): Promise<Cookie | undefined>

指定された Cookie データで Cookie を設定します。同等の Cookie が存在する場合は上書きされる可能性があります。

パラメータ

  • 詳細

    オブジェクト

    設定される Cookie の詳細。

    • ドメイン

      文字列 省略可

      Cookie のドメイン。省略すると、Cookie はホスト専用 Cookie になります。

    • expirationDate

      number 省略可

      UNIX エポックからの秒数で表した Cookie の有効期限。省略すると、Cookie はセッション Cookie になります。

    • httpOnly

      boolean 省略可

      Cookie を HttpOnly としてマークするかどうか。デフォルトは false です。

    • name

      文字列 省略可

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

    • partitionKey

      CookiePartitionKey 省略可

      Chrome 119 以降 Chrome 148 以降の browser.*

      Partitioned 属性を持つ Cookie の読み取りまたは変更に使用するパーティション キー。

    • パス

      文字列 省略可

      Cookie のパス。デフォルトは、url パラメータのパス部分です。

    • sameSite

      SameSiteStatus 省略可

      Chrome 51 以降 Chrome 148 以降の browser.*

      Cookie の SameSite ステータス。デフォルトは「unspecified」です。つまり、省略すると、SameSite 属性を指定せずに Cookie が設定されます。

    • 安全

      boolean 省略可

      Cookie を Secure としてマークするかどうか。デフォルトは false です。

    • storeId

      文字列 省略可

      Cookie を設定する Cookie ストアの ID。デフォルトでは、Cookie は現在の実行コンテキストの Cookie ストアに設定されます。

    • URL

      文字列

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

    • 値

      文字列 省略可

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

戻り値

  • Promise<Cookie | undefined>

    Chrome 88 以降 Chrome 148 以降の browser.*

イベント

onChanged

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

Cookie が設定または削除されたときに呼び出されます。特殊なケースとして、Cookie のプロパティの更新は 2 段階のプロセスとして実装されます。更新対象の Cookie が最初に完全に削除され、「cause」が「overwrite」の通知が生成されます。その後、更新された値を含む新しい Cookie が書き込まれ、"cause" "explicit" を含む 2 番目の通知が生成されます。

パラメータ

  • callback

    関数

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

    (changeInfo: object) => void

    • changeInfo

      オブジェクト

      • Cookie の変更の根本的な理由。

      • Cookie

        Cookie

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

      • 削除済み

        ブール値

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