Google は AI 技術を使用して、コンテンツをご希望の言語に翻訳しています。AI 翻訳には誤りが含まれる場合があります。

API キーで API アクセスを制限する

OpenAPI | gRPC

API キーを使用すると、特定の API メソッドまたは API のすべてのメソッドに対するアクセスを制限できます。このページでは、API キーのあるクライアントに対する API アクセスの制限方法と API キーの作成方法について説明します。

Extensible Service Proxy（ESP）は Service Control API を使用して、API キーと、その API キーとプロジェクトで有効にされた API との関連付けを検証します。API キーを必須とするように API が設定されている場合は、保護されたメソッド、クラス、API へのリクエストは適切なキーがない限り拒否されます。適切なキーとは、プロジェクト内で生成されたものか、API を有効にする権限を付与されたデベロッパーに属する別のプロジェクトで生成されたもののことです。 API キーがどのプロジェクトで作成されたかはログに記録されず、リクエストヘッダーにも追加されません。ただし、特定のコンシューマプロジェクトのフィルタリングに記載されているとおり、クライアントが関連付けられているプロジェクトは、 Google Cloud [エンドポイント] > [サービス] に表示されます。

API キーの作成が必要な Google Cloud プロジェクトについては、API キーにより保護されている API を共有するをご覧ください。

すべての API メソッドへのアクセスを制限する

API のすべてのメソッドへのアクセスに API キーを要求するには:

OpenAPI 2.0

テキストエディタでプロジェクトの openapi.yaml ファイルを開きます。
securityDefinitions: で、サンプルコードスニペットに示すように、api_key: 値 apiKey、key、query を追加します。
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
これにより、api_key という「セキュリティスキーム」が確立され、API の保護に使用できるようになります。その他の api_key 定義オプションについては、API キー定義の制限事項をご覧ください。
ファイルのトップレベル（インデントやネストのないレベル）にある security ディレクティブに api_key: [] を追加します。security ディレクティブを追加する必要がある場合と、すでに存在する場合とがあります。
```
security:
  - api_key: []
```
このディレクティブを使用すると、api_key セキュリティスキームがファイル内のすべてのメソッドに適用されます。角かっこの中には何も入れないでください。OpenAPI 仕様では、OAuth を使用しないセキュリティスキームの場合は空のリストが必要です。

OpenAPI 3.x

テキストエディタでプロジェクトの openapi.yaml ファイルを開きます。
components.securitySchemes: に以下を追加します。
```
components:
  securitySchemes:
    api_key:
      type: "apiKey"
      name: "key"
      in: "query"
```
これにより、api_key という「セキュリティスキーム」が確立され、API の保護に使用できるようになります。
ファイルのトップレベル（インデントやネストのないレベル）にある security ディレクティブに api_key: [] を追加します。
```
security:
  - api_key: []
```
このディレクティブを使用すると、api_key セキュリティスキームがファイル内のすべてのメソッドに適用されます。

特定の API メソッドへのアクセスを制限する

特定のメソッドの API キーを取得するには:

OpenAPI 2.0

テキストエディタでプロジェクトの openapi.yaml ファイルを開きます。
ファイルのトップレベル（インデントやネストのないレベル）に空のセキュリティディレクティブを追加して、API 全体にこのディレクティブを適用します。
```
security: []
```
securityDefinitions: で、サンプルコードスニペットに示すように、api_key: 値 apiKey、key、query を追加します。
```
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "key"
    in: "query"
```
これにより、api_key という「セキュリティスキーム」が確立され、API の保護に使用できるようになります。その他の api_key 定義オプションについては、API キー定義の制限事項をご覧ください。
メソッドの定義の security ディレクティブに api_key: [] を追加します。
```
...
paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      security:
      - api_key: []
      produces:
      ...
```
このディレクティブを使用すると、api_key セキュリティスキームがこのメソッドに適用されます。角かっこの中には何も入れないでください。OpenAPI 仕様では、OAuth を使用しないセキュリティスキームの場合は空のリストが必要です。

OpenAPI 3.x

テキストエディタでプロジェクトの openapi.yaml ファイルを開きます。
ファイルのトップレベル（インデントやネストのないレベル）に空のセキュリティディレクティブを追加して、API 全体にこのディレクティブを適用します。
```
security: []
```
components.securitySchemes: に以下を追加します。
```
components:
  securitySchemes:
    api_key:
      type: "apiKey"
      name: "key"
      in: "query"
```
これにより、api_key という「セキュリティスキーム」が確立され、API の保護に使用できるようになります。

メソッドの定義の security ディレクティブに api_key: [] を追加します。

...
paths:
  /echo:
    post:
      description: "Echo back a given message."
      operationId: "echo"
      security:
      - api_key: []
      requestBody:
      ...

このディレクティブを使用すると、api_key セキュリティスキームがこのメソッドに適用されます。

メソッドの API キー制限を削除する

API のアクセスを制限している場合に、特定のメソッドについてのみ API キー検証を無効にするには:

OpenAPI 2.0

テキストエディタでプロジェクトの openapi.yaml ファイルを開きます。

メソッドの定義に、空の security ディレクティブを追加します。

  ...
  paths:
    "/echo":
      post:
        description: "Echo back a given message."
        operationId: "echo"
        security: []
        produces:
        ...

OpenAPI 3.x

テキストエディタでプロジェクトの openapi.yaml ファイルを開きます。

メソッドの定義に、空の security ディレクティブを追加します。

  ...
  paths:
    /echo:
      post:
        description: "Echo back a given message."
        operationId: "echo"
        security: []
        requestBody:
        ...

API キーを使って API を呼び出す

API または API メソッドで API キーが必要とされる場合、次の curl の例に示すように、key というクエリパラメータを使用してキーを提供します。

 curl "${ENDPOINTS_HOST}/echo?key=${ENDPOINTS_KEY}"

ここで、ENDPOINTS_HOST は API ホスト名を格納する環境変数、ENDPOINTS_KEY は API キーを格納する環境変数です。

API キーにより保護されている API を共有する

API キーは、作成されたプロジェクト Google Cloud に関連付けられます。API に API キーを要求することにした場合、API キーが作成されるプロジェクトは、 Google Cloud 次の質問への回答によって異なります。

API の個々の呼び出し元を互いに区別して、割り当てなどの Endpoints 機能を使用できるようにする必要があるか。
API のすべての呼び出し元に独自の Google Cloud プロジェクトがあるか。
異なる API キー制限を設定する必要があるか。

どの Google Cloud プロジェクトで API キーを作成するかを決定するためのガイドとして、以下のディシジョンツリーを使用できます。

API を有効にする権限を付与する

API の個々の呼び出し元を区別する必要があり、呼び出し元ごとに独自の Google Cloud プロジェクトがある場合、各自の Google Cloud プロジェクトで API を有効にする権限をプリンシパルに付与できます。これにより、ユーザーは API で使用する API キーを各自で作成できます。

たとえば、社内のさまざまなクライアントプログラムが使用する API をチームが作成し、各クライアントプログラムに独自の Google Cloudプロジェクトが関連付けられているとします。API の呼び出し元を区別するには、各呼び出し元の API キーをそれぞれのプロジェクトで作成する必要があります。 Google Cloud この場合、クライアントプログラムのプロジェクト Google Cloud で API を有効にする権限をプロジェクトのメンバーに付与します。

ユーザーが独自の API キーを作成できるようにするには:

API が構成されている Google Cloud プロジェクトで、API を有効にする権限を各ユーザーに付与します。
ユーザーに連絡して、各自の Google Cloudプロジェクトで API を有効にして API キーを作成できることを伝えます。

呼び出し元ごとに個別の Google Cloud プロジェクトを作成する

API の個々の呼び出し元を区別する必要がある場合、すべての呼び出し元が Google Cloud プロジェクトを持っているとは限らない状況では、呼び出し元ごとに個別の Google Cloud プロジェクトと API キーを作成できます。プロジェクトを作成する前に、プロジェクト名について考慮してください。そうすれば、プロジェクトに関連付けられた呼び出し元を簡単に識別できます。

たとえば、API を利用する外部ユーザーがあり、API を呼び出すクライアントプログラムの作成方法がわからないとします。クライアントによっては、サービスを使用して Google Cloud プロジェクトを持っている場合や、 Google Cloud そうでない場合があるでしょう。個々の呼び出し元を区別するには、呼び出し元ごとに個別の Google Cloud プロジェクトと API キーを作成する必要があります。

呼び出し元ごとに個別の Google Cloud プロジェクトと API キーを作成するには:

呼び出し元ごとに個別のプロジェクトを作成します。
各プロジェクトで、API を有効化して API キーを作成します。
それぞれの呼び出し元に API キーを付与します。

呼び出し元ごとに API キーを作成する

API の呼び出し元を区別する必要はないものの、API キーの制限を追加する必要がある場合は、同じプロジェクト内で呼び出し元ごとに個別の API キーを作成できます。

同じプロジェクト内で呼び出し元ごとに API キーを作成するには:

API が構成されているプロジェクトまたは API が有効化されているプロジェクトで、API キー制限が必要なユーザーごとに API キーを作成します。
それぞれの呼び出し元に API キーを付与します。

すべての呼び出し元に同じ API キーを作成する

API の呼び出し元を区別する必要も、API の制限を追加する必要もないが、（匿名アクセスを防ぐなどの目的で）API キーを要求する場合は、すべての呼び出し元が使用する 1 つの API キーを作成できます。

すべての呼び出し元に同じ API キーを作成するには:

API が構成されているプロジェクトまたは API が有効化されているプロジェクトで、必要なAPI キー制限を持つすべての呼び出し元に使用する API キーを作成します。
すべての呼び出し元に同じ API キーを付与します。

アプリケーションの制限

アプリケーションの制限では、API キーの使用を許可するウェブサイト、IP アドレス、またはアプリを指定します。詳細については、アプリケーションの制限を追加するをご覧ください。

注: HTTP リファラー（ウェブサイト） をアプリケーションの制限として使用する場合は、ウェブサイトの制限を追加するときにスキーム（https:// など）を含める必要があります。たとえば、https://example.com/* は有効な制限ですが、example.com/* は無効です。

ベストプラクティス

API キーを使用して API とユーザーデータへのアクセスを保護する場合は、Extensible Service Proxy V2（ESPv2）の起動オプションの構成時に必ず --service_control_network_fail_policy フラグを close に設定してください。フラグのデフォルト値は open. です。

ESPv2 は Service Control を呼び出して API キーを検証します。Service Control への接続中にネットワーク障害が発生し、ESPv2 で API キーを検証できない場合、不正なキーで API に対して行われるリクエストはすべて拒否されます。

API キーで API アクセスを制限する コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

すべての API メソッドへのアクセスを制限する

OpenAPI 2.0

OpenAPI 3.x

特定の API メソッドへのアクセスを制限する

OpenAPI 2.0

OpenAPI 3.x

メソッドの API キー制限を削除する

OpenAPI 2.0

OpenAPI 3.x

API キーを使って API を呼び出す

API キーにより保護されている API を共有する

API を有効にする権限を付与する

呼び出し元ごとに個別の Google Cloud プロジェクトを作成する

呼び出し元ごとに API キーを作成する

すべての呼び出し元に同じ API キーを作成する

アプリケーションの制限

ベスト プラクティス

次のステップ

API キーで API アクセスを制限する

ベストプラクティス