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。

例

Cookie API を使用した簡単な例については、 examples/api/cookies ディレクトリがあります。その他の例や表示方法については、 サンプルをご覧ください。

型

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

プロパティ

  • ドメイン

    文字列

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

  • expirationDate

    数値（省略可）

    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

    ブール値（省略可）

    保留中

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

  • topLevelSite

    文字列（省略可）

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

CookieStore

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

プロパティ

  • id

    文字列

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

  • tabIds

    数値 []

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

OnChangedCause

Chrome 44 以降

Cookie が変更された根本的な理由。「chrome.cookies.remove」の明示的な呼び出しによって Cookie が挿入、削除された場合、「原因」「露骨な表現」になります。Cookie の有効期限により自動的に削除された場合は、「原因」となる「期限切れ」になります。すでに期限切れになっている有効期限で上書きされたために Cookie が削除された場合、「原因」"expired_overwrite"に設定されます。ガベージ コレクションが原因で Cookie が自動的に削除された場合、「強制排除」されます。Cookie が「設定」により自動的に削除された場合呼び出す必要はありません。「上書き」されます。それに応じて対応を計画してください。

列挙型

SameSiteStatus

Chrome 51 以降

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

列挙型

メソッド

get()

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

1 つの Cookie に関する情報を取得します。指定した URL に同じ名前の 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 をフィルタする情報。

    • ドメイン

      文字列（省略可）

      取得した 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 以降

    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 |未定義>

    Chrome 88 以降

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

set()

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

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

パラメータ

  • 詳細

    オブジェクト

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

    • ドメイン

      文字列（省略可）

      Cookie のドメイン。省略した場合、Cookie はホストのみの Cookie になります。

    • expirationDate

      数値（省略可）

      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 をセキュアとしてマークするかどうか。デフォルトは false です。

    • storeId

      文字列（省略可）

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

    • URL

      文字列

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

    • 値

      文字列（省略可）

      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 がまず完全に削除され、「原因」を示す通知が生成されます。「上書きする」オプションををタップします。その後、更新された値で新しい Cookie が書き込まれ、「cause」を含む 2 番目の通知が生成されます。「露骨な表現」として扱われます。

パラメータ

  • callback

    関数

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

    (changeInfo: object) => void

    • changeInfo

      オブジェクト

      • Cookie が変更された根本的な理由。

      • Cookie

        Cookie

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

      • 削除済み

        ブール値

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