API 構成の作成
前提条件
API 構成を作成する前に、次のことを確認してください。
開発環境の構成の説明に従って、開発環境を準備済みである。
OpenAPI 仕様としてAPI 定義を作成済みである。
必要に応じて、API の作成の説明に沿って API を作成している。API が存在しない場合は、API 構成を作成すると作成されます。
API 構成 ID の要件
以下に示す gcloud
コマンドの多くでは、CONFIG_ID の形式で API 構成の ID を指定する必要があります。API Gateway では、API 構成 ID に次の要件が適用されます。
- 値の最大長は 63 文字です。
- 使用できるのは小文字、数字、ダッシュのみです。
- ダッシュで始めることはできません。
- アンダースコアを含めることはできません。
API 構成の作成
Google Cloud CLI を使用して API 定義をアップロードし、API 構成を作成します。API 定義をアップロードする際には、API の名前を指定する必要があります。API Gateway に API が存在しない場合は、このコマンドによって作成も行われます。
API 構成を作成するには:
API 定義を含むディレクトリに移動します。
API 定義の OpenAPI 仕様の作成の詳細については、OpenAPI の概要とクイックスタート: API Gateway に API をデプロイするをご覧ください。
gRPC サービス定義と API 定義の構成の詳細については、gRPC サービスの構成と API Gateway と Cloud Run for gRPC のスタートガイドをご覧ください。
次のコマンドで返されるプロジェクト ID を検証して、サービスが間違ったプロジェクト内に作成されないようにします。
gcloud config list project
デフォルト プロジェクトを変更する必要がある場合は、次のコマンドを実行します。このとき PROJECT_ID を、サービスを作成する Google Cloud プロジェクトの ID に置き換えます。
gcloud config set project PROJECT_ID
api-configs create
コマンドのヘルプを表示します。gcloud api-gateway api-configs create --help
次のコマンドを実行して API 構成を作成します。
gcloud api-gateway api-configs create CONFIG_ID \ --api=API_ID --openapi-spec=API_DEFINITION \ --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL
ここで
- CONFIG_ID は、新しい API の ID を指定します。
- API_ID は、この API 構成に関連付けられた API Gateway API の ID を指定します。API が存在しない場合は、このコマンドによって作成されます。
- API_DEFINITION は、API 定義を含む OpenAPI 仕様の名前を指定します。
- PROJECT_ID は、Google Cloud プロジェクト ID を指定します。
- SERVICE_ACCOUNT_EMAIL には、認証が構成されたバックエンドのトークンの署名に使用するサービス アカウントを指定します。詳細については、サービス アカウントの構成をご覧ください。
API と API 構成の作成時に、API Gateway は情報をターミナルに出力します。API 構成がダウンストリームのシステムに伝播される際に、このオペレーションが完了するまでに数分を要する場合があります。複雑な API 構成の作成が正常に完了するまでに最大 10 分を要する場合があります。構成の作成中は、同じ API で別の構成を作成しようとしないでください。API に対して一度に作成できる構成は 1 つのみです。
正常に完了したら、次のコマンドを使用して新しい API 構成の詳細を表示できます。
gcloud api-gateway api-configs describe CONFIG_ID \ --api=API_ID --project=PROJECT_ID
このコマンドを実行すると、次のようなフィード レスポンスが返されます。
createTime: '2020-02-04T18:33:11.882707149Z' displayName: CONFIG_ID gatewayConfig: backendConfig: googleServiceAccount: 1111111@developer.gserviceaccount.com labels: '' name: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID serviceRollout: rolloutId: 2020-02-04r2 state: ACTIVE updateTime: '2020-02-04T18:33:12.219323647Z'
API のマネージド サービス名を使用して API を有効にします。この値は、API ランディング ページの API の [マネージド サービス] 列で確認できます。
gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog
このコマンドは、API を作成するときに 1 回だけ実行する必要があります。後で API を変更しても、コマンドを再実行する必要はありません。
Google Cloud CLI には、gcloud リファレンスで説明されているオプションなど、多くのオプションがあります。さらに、API Gateway では、API 構成の作成時に次のオプションを設定できます。
--async
: オペレーションの完了を待たずに、直ちに制御をターミナルに戻します。--display-name=NAME
: API 構成の表示名、つまり UI に表示される名前を指定します。名前にスペースを使用しないでください。代わりにハイフンとアンダースコアを使用してください。デフォルト値は CONFIG_ID です。--labels=KEY1=VALUE1,KEY2=VALUE2,...
: API 構成に関連付けられたラベルを指定します。
次に例を示します。
gcloud api-gateway api-configs create CONFIG_ID \ --api=API_ID --openapi-spec=API_DEFINITION \ --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL \ --async --display-name=MyConfig --labels=a=1,b=2
ラベルは、上記の describe
コマンドの出力で確認できます。また、--format
オプションを含めると list
コマンドでも確認できます。
gcloud api-gateway api-configs list \ --api=API_ID --project=PROJECT_ID --format="table(name, labels)"
API 構成の一覧表示
特定のプロジェクトの API 構成を一覧表示するには:
gcloud api-gateway api-configs list --project=PROJECT_ID
このコマンドを実行すると、次のようなフィード レスポンスが返されます。
NAME DISPLAY_NAME ROLLOUT_ID STATE CREATE_TIME projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID CONFIG_ID 2020-02-04r0 ACTIVE 2020-02-04T16:18:02.369859863Z
プロジェクト内の特定の API の API 構成を一覧表示するには:
gcloud api-gateway api-configs list --api=API_ID --project=PROJECT_ID
プロジェクト、API、構成 ID を使用して、API 構成に関する詳細情報を取得します。
gcloud api-gateway api-configs describe CONFIG_ID \ --api=API_ID --project=PROJECT_ID
API 構成の更新
既存の API 構成は、ラベルと表示名の更新を除き変更できません。
既存の API 構成を更新するには、次の gcloud
を使用します。
--display-name
--update-labels
--clear-labels
--remove-labels
次に例を示します。
gcloud api-gateway api-configs update CONFIG_ID \ --api=API_ID --project=PROJECT_ID \ --update-labels=a=1,b=2
すべての更新オプションを表示するには、次のコマンドを使用します。
gcloud api-gateway api-configs update --help
API 構成の削除
既存の API 構成を削除するには、次の gcloud
コマンドを使用します。
gcloud api-gateway api-configs delete CONFIG_ID --api=API_ID --project=PROJECT_ID