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 構成を作成するには:

  1. API 定義を含むディレクトリに移動します。

    API 定義の OpenAPI 仕様の作成の詳細については、OpenAPI の概要クイックスタート: API Gateway に API をデプロイするをご覧ください。

    gRPC サービス定義と API 定義の構成の詳細については、gRPC サービスの構成API Gateway と Cloud Run for gRPC のスタートガイドをご覧ください。

  2. 次のコマンドで返されるプロジェクト ID を検証して、サービスが間違ったプロジェクト内に作成されないようにします。

    gcloud config list project

    デフォルト プロジェクトを変更する必要がある場合は、次のコマンドを実行します。このとき PROJECT_ID を、サービスを作成する Google Cloud プロジェクトの ID に置き換えます。

    gcloud config set project PROJECT_ID
  3. api-configs create コマンドのヘルプを表示します。

    gcloud api-gateway api-configs create --help
  4. 次のコマンドを実行して 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 つのみです。

  5. 正常に完了したら、次のコマンドを使用して新しい 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'
  6. 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

次のステップ