chrome.cookies

説明

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

権限

cookies

Cookie API を使用するには、アクセスする Cookie のホストのホスト権限とともに、マニフェストで "cookies" 権限を宣言します。次に例を示します。

{
  "name": "My extension",
  ...
  "host_permissions": [
    "*://*.google.com/"
  ],
  "permissions": [
    "cookies"
  ],
  ...
}

パーティショニング

パーティショニングされた Cookie を使用すると、特定の Cookie をトップレベル フレームのオリジンに対してキー設定する必要があることをサイトがマークできます。つまり、たとえば、サイト A がサイト B とサイト C の iframe を使用して埋め込まれている場合、A のパーティション化された Cookie の埋め込みバージョンは B と C で異なる値を持つことができます。

デフォルトでは、すべての API メソッドはパーティショニングされていない Cookie で動作します。partitionKey プロパティを使用すると、この動作をオーバーライドできます。

拡張機能のパーティショニングの一般的な影響について詳しくは、ストレージと Cookie をご覧ください。

例

Cookie API の使用例については、examples/api/cookies ディレクトリをご覧ください。その他の例や、ソースコードの表示に関するヘルプについては、サンプルをご覧ください。

型

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

プロパティ

  • ドメイン

    文字列

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

  • expirationDate

    number 省略可

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

  • hostOnly

    ブール値

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

  • httpOnly

    ブール値

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

  • name

    文字列

    Cookie の名前。

  • partitionKey

    CookiePartitionKey 省略可

    Chrome 119 以降

    Partitioned 属性で Cookie を読み取りまたは変更するためのパーティション キー。

  • パス

    文字列

    Cookie のパス。

  • sameSite

    SameSiteStatus

    Chrome 51 以降

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

  • 安全

    ブール値

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

  • セッション

    ブール値

    Cookie が有効期限付きの永続 Cookie ではなくセッション Cookie の場合は true。

  • storeId

    文字列

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

  • 値

    文字列

    Cookie の値。

CookieDetails

Chrome 88 以降

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

プロパティ

  • name

    文字列

    アクセスする Cookie の名前。

  • partitionKey

    CookiePartitionKey 省略可

    Chrome 119 以降

    Partitioned 属性で Cookie を読み取りまたは変更するためのパーティション キー。

  • storeId

    文字列 省略可

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

  • URL

    文字列

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

CookiePartitionKey

Chrome 119 以降

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

プロパティ

  • hasCrossSiteAncestor

    ブール値（省略可）

    Chrome 130 以降

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

  • topLevelSite

    文字列 省略可

    パーティション化された Cookie が利用可能なトップレベル サイト。

CookieStore

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

プロパティ

  • id

    文字列

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

  • tabIds

    number[]

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

FrameDetails

Chrome 132 以降

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

プロパティ

  • documentId

    文字列 省略可

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

  • frameId

    number 省略可

    タブ内のフレームの一意の識別子。

  • tabId

    number 省略可

    フレームを含むタブの一意の識別子。

OnChangedCause

Chrome 44 以降

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

列挙型

"evicted"

"expired"

"explicit"

"expired_overwrite"

"overwrite"

SameSiteStatus

Chrome 51 以降

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()

Promise 
chrome.cookies.get(
  details: CookieDetails,
  callback?: function,
): Promise<Cookie | undefined>

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

パラメータ

  • 詳細

    CookieDetails

  • callback

    関数 省略可

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

    (cookie?: Cookie) => void

    • Cookie

      Cookie 省略可

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

戻り値

  • Promise<Cookie | undefined>

    Chrome 88 以降

getAll()

Promise 
chrome.cookies.getAll(
  details: object,
  callback?: function,
): Promise<Cookie[]>

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

パラメータ

  • 詳細

    オブジェクト

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

    • ドメイン

      文字列 省略可

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

    • name

      文字列 省略可

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

    • partitionKey

      CookiePartitionKey 省略可

      Chrome 119 以降

      Partitioned 属性で Cookie を読み取りまたは変更するためのパーティション キー。

    • パス

      文字列 省略可

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

    • 安全

      ブール値（省略可）

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

    • セッション

      ブール値（省略可）

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

    • storeId

      文字列 省略可

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

    • URL

      文字列 省略可

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

  • callback

    関数 省略可

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

    (cookies: Cookie[]) => void

    • Cookie

      Cookie[]

      指定された Cookie 情報に一致する、既存の有効期限切れでないすべての Cookie。

戻り値

  • Promise<Cookie[]>

    Chrome 88 以降

getAllCookieStores()

Promise 
chrome.cookies.getAllCookieStores(
  callback?: function,
): Promise<CookieStore[]>

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

パラメータ

  • callback

    関数 省略可

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

    (cookieStores: CookieStore[]) => void

    • cookieStores

      CookieStore[]

      既存の Cookie ストアすべて。

戻り値

getPartitionKey()

Promise Chrome 132 以降 
chrome.cookies.getPartitionKey(
  details: FrameDetails,
  callback?: function,
): Promise<object>

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

パラメータ

  • 詳細

    FrameDetails

  • callback

    関数 省略可

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

    (details: object) => void

    • 詳細

      オブジェクト

      取得されたパーティション キーに関する詳細が含まれます。

      • partitionKey

        CookiePartitionKey

        Partitioned 属性で Cookie を読み取りまたは変更するためのパーティション キー。

戻り値

  • Promise<object>

remove()

Promise 
chrome.cookies.remove(
  details: CookieDetails,
  callback?: function,
): Promise<object | undefined>

名前で 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 以降

set()

Promise 
chrome.cookies.set(
  details: object,
  callback?: function,
): Promise<Cookie | undefined>

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

パラメータ

  • 詳細

    オブジェクト

    設定されている Cookie の詳細。

    • ドメイン

      文字列 省略可

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

    • expirationDate

      number 省略可

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

    • httpOnly

      ブール値（省略可）

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

    • name

      文字列 省略可

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

    • partitionKey

      CookiePartitionKey 省略可

      Chrome 119 以降

      Partitioned 属性で Cookie を読み取りまたは変更するためのパーティション キー。

    • パス

      文字列 省略可

      Cookie のパス。デフォルトでは、url パラメータのパス部分が使用されます。

    • sameSite

      SameSiteStatus 省略可

      Chrome 51 以降

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

    • 安全

      ブール値（省略可）

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

    • storeId

      文字列 省略可

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

    • URL

      文字列

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

    • 値

      文字列 省略可

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

  • callback

    関数 省略可

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

    (cookie?: Cookie) => void

    • Cookie

      Cookie 省略可

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

戻り値

  • Promise<Cookie | undefined>

    Chrome 88 以降

イベント

onChanged

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

Cookie が設定または削除されたときに発生します。特殊なケースとして、Cookie のプロパティの更新は 2 段階のプロセスとして実装されます。更新される Cookie は最初に完全に削除され、「原因」が「上書き」の通知が生成されます。その後、更新された値で新しい Cookie が書き込まれ、「原因」が「明示的」の 2 つ目の通知が生成されます。

パラメータ

  • callback

    関数

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

    (changeInfo: object) => void

    • changeInfo

      オブジェクト

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

      • Cookie

        Cookie

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

      • 削除済み

        ブール値

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