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

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

API で API キーを義務付けるように設定すると、プロジェクトで生成されたキー、または API 有効化を許可したデベロッパーの別のプロジェクトで生成されたキーがない限り、保護されたメソッド、クラスまたは API へのリクエストが拒否されます。API キーが作成されたプロジェクトはロギングされず、リクエスト ヘッダーに追加されません。ただし、特定のユーザー プロジェクトのフィルタに記載されているとおり、クライアントが関連付けられている GCP プロジェクトが [エンドポイント] の [サービス] ページに表示されます。

どの GCP プロジェクトで API キーを作成すべきかについては、API キーにより保護されている API を共有するをご覧ください。

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

API のすべての呼び出しで API キーを義務付けるには、apiKeyRequired = AnnotationBoolean.TRUE@Api アノテーションに追加します。次に例を示します。

@Api(
  name = "echo",
  version = "v1",
  apiKeyRequired = AnnotationBoolean.TRUE
  )
public class Echo {
//API class and methods...
}

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

特定の API メソッドに対するすべての呼び出しで API キーを義務付けるには、apiKeyRequired = AnnotationBoolean.TRUE@ApiMethod アノテーションに追加します。次に例を示します。

@ApiMethod(name = "echo_api_key", path = "echo_api_key", apiKeyRequired = AnnotationBoolean.TRUE)
public Message echoApiKey(Message message, @Named("n") @Nullable Integer n) {
  return doEcho(message, n);
}

特定の API クラスに対するすべての呼び出しで API キーを義務付けるには、apiKeyRequired = AnnotationBoolean.TRUE@ApiClass アノテーションに追加します。

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

API または API メソッドに関する API キー検証を無効にするには、api_key_required=True(Python の場合)または apiKeyRequired = AnnotationBoolean.TRUE(Java の場合)を、API またはメソッドのデコレータやアノテーションから削除します。その後、再コンパイルして再度デプロイします。

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

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

curl \
    -H "Content-Type: application/json" \
    -X POST \
    -d '{"message": "echo"}' \
    "${HOST}/_ah/api/echo/v1/echo_api_key?key=${API_KEY}"

HOSTAPI_KEY は、それぞれ API ホスト名と API キーを格納する変数です。echo は API の名前で置き換え、v1 は API のバージョンで置き換えます。

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

API キーは、それらが作成される Google Cloud Platform(GCP)プロジェクトに関連付けられます。API で API キーを必須とするよう決定した場合、どの GCP プロジェクトで API キーが作成されるかは、次の質問の答えによって異なります。

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

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

API キー ディシジョン ツリー

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

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

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

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

  1. API が構成されている GCP プロジェクトで、API を有効にする権限を各ユーザーに付与します。
  2. 各ユーザーと連絡を取り、ユーザーの GCP プロジェクトで API を有効化したり API キーを作成したりできるようになったことを知らせます。

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

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

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

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

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

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

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

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

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

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

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

すべての呼び出し元に同じ API キーを作成するには:
  1. API が構成されているプロジェクトまたは API が有効になっているプロジェクトで、すべての呼び出し元に使用する API キーを作成します。
  2. すべての呼び出し元に同じ API キーを付与します。

次のステップ

このページは役立ちましたか?評価をお願いいたします。

フィードバックを送信...

App Engine 用 Cloud Endpoints Frameworks
ご不明な点がありましたら、Google のサポートページをご覧ください。