CLI を使用して API Hub をプロビジョニングする

このページは Apigee と Apigee ハイブリッドに適用されます。

このセクションでは、コマンドラインを使用して API Hub をプロビジョニングする方法について説明します。

ステップの概要

プロビジョニングの手順は次のとおりです。

API Hub の前提条件を満たしていることを確認します。
ステップ 1: API を有効にする。Apigee では、いくつかの Google Cloud APIs を有効にする必要があります。
ステップ 2: 環境変数を定義する。環境変数は、コマンド実行時に整合性を保つのに役立ちます。
ステップ 3: サービスアカウントと CMEK を作成する。このサービスアカウントは、Google Cloud クライアントライブラリで Google Cloud APIs による認証に使用されます。内部 API に関する情報は機密と見なされる可能性があるため、CMEK による保存データの暗号化と復号（保護）が必要です。CMEK は、インスタンスのロケーションと同じリージョンに存在する必要があります。
ステップ 4: インスタンスを作成する。インスタンスは、プロジェクトと関連サービスが保存される場所です。
インスタンスのステータスを確認する（省略可）。インスタンスの作成には時間がかかる場合があるため、このコマンドを使用してステータスを確認します。
インスタンスを削除する（省略可）。インスタンスを削除する必要がある場合は、このコマンドを使用します。
オペレーションのステータスを確認する（省略可）。このコマンドを使用して、長時間実行オペレーションのステータスを確認します。

ステップ 1: API を有効にする

API Hub を使用するには、プロジェクトで次の API を有効にする必要があります。

Apigee Registry API: API Hub は API Registry と連携して、組織の API の表示と管理を行います。
Cloud Key Management Service（KMS）API: 顧客が暗号鍵を管理し、それらの鍵を使用して暗号オペレーションを実行できます。
Service Usage API: サービスコンシューマが Google Cloud Platform 上で使用するサービスを有効にしたり、利用可能なサービスまたは有効になっているサービスの一覧を表示したり、サービスコンシューマが使用しなくなったサービスを無効にしたりします。

Google Cloud コンソール UI または CLI を使用して API を有効にできます。

コンソール

UI を使用して API を有効にするには、Google Cloud コンソールで次の手順に沿って操作します。

Apigee Registry API を有効にします。

Apigee Registry API の有効化の設定に移動

[有効にする] をクリックします。

これで、Google Cloud プロジェクトでこの API を利用できるようになります。
Cloud Key Management Service（KMS）API を有効にします。

Cloud KMS API の有効化の設定に移動

[有効にする] をクリックします。

これで、Google Cloud プロジェクトでこの API を利用できるようになります。
Service Usage API を有効にします。
Service Usage API の有効化の設定に移動

[有効にする] をクリックします。

これで、Google Cloud プロジェクトでこの API を利用できるようになります。
これらの API が有効になっているかどうかは以下で確認できます。
[有効な API とサービス] に移動

追加した API は、有効な API のリストに表示されます。
- Apigee Registry API
- Cloud Key Management Service（KMS）API
- Service Usage API

gcloud

次のコマンドを実行します。

gcloud services enable \
    apigeeregistry.googleapis.com \
    cloudkms.googleapis.com \
    serviceusage.googleapis.com --project=PROJECT_ID

ここで、PROJECT_ID は Google Cloud コンソールプロジェクトの名前です。

（省略可）処理を確認するには、services list コマンドを使用して、有効な API をすべて表示します。
```
gcloud services list
```
レスポンスには、有効にした API を含むすべての有効なサービスが表示されます。

ステップ 2: 環境変数を定義する

環境変数を使用することで整合性が保たれ、後のステップでドキュメントの手順に沿った操作が容易になります。

次の環境変数を定義し、動的変数を実際の値に置き換えます。
```
export TOKEN=$(gcloud auth print-access-token)

# ----- Set key_ring_name and key_name to values that will help you identify the API hub encryption key in future. -----
export KEY_RING_NAME=YOUR_KEY_RING_NAME
export KEY_NAME=YOUR_KEY_NAME

export PROJECT_ID=YOUR_PROJECT_ID
export RUNTIME_LOCATION=YOUR_RUNTIME_LOCATION

# -----If you already have a CMEK, define this environment variable-----
export CMEK_KEY_ID=YOUR_CMEK_KEY_ID
```
ここで
- TOKEN は、Apigee Registry API の呼び出しを認証および承認するトークンです。Authentication ヘッダーで署名なしトークンとして渡す必要があります。なお、トークンは一定期間経過すると期限切れになりますが、同じコマンドを使用して簡単に再生成できます。詳細については、print-access-token コマンドのリファレンスページをご覧ください。
- KEY_RING_NAME は、暗号化キーリングを識別するために使用するキーリングの名前です。
- KEY_NAME は、API Hub の暗号鍵を識別するために使用する鍵の名前です。
- PROJECT_ID は、前提条件で作成した Cloud プロジェクト ID です。
- RUNTIME_LOCATION は、後で作成する Apigee Registry インスタンスが配置される物理的なロケーションです。CMEK 鍵は、ランタイムのロケーションと同じリージョンに存在する必要があります。
  注:
  RUNTIME_LOCATION には、ゾーン名ではなくリージョン名を使用してください。たとえば、us-west1 はリージョン名で、us-west1-a はリージョン内のゾーンです。リージョンとゾーンの識別もご覧ください。
  
  使用可能なランタイムロケーションのリストについては、Apigee のロケーションをご覧ください。
- CMEK_KEY_ID は、顧客管理の暗号鍵の鍵 ID です。鍵のローテーションは現在サポートされていません。
  
  鍵 ID の構文は次のとおりです（ファイルパスに似ています）。
```
projects/PROJECT_ID/locations/RUNTIME_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME
```
（省略可）設定した値をエコーして作業内容を確認します。コマンドで変数を使用する場合は、変数名の前にドル記号（$）を付けます。
```
echo $TOKEN
echo $KEY_RING_NAME
echo $KEY_NAME
echo $PROJECT_ID
echo $RUNTIME_LOCATION

# -----If you already have a CMEK-----
echo $CMEK_KEY_ID
```

ステップ 3: サービスアカウントと CMEK を作成する

このセクションでは、サービスアカウント、暗号キーリング、鍵を作成する方法について説明します。

プロジェクトごとに、それぞれのプロダクトに対して個別のサービスアカウントを Apigee Registry に作成します。

注: このコマンドは、サービスアカウントがすでに作成されている場合でも複数回実行できます。
```
gcloud beta services identity create --service=apigeeregistry.googleapis.com --project=$PROJECT_ID
```
返されるサービスアカウントは次のようになります。
```
service-755582297973@gcp-sa-apigeeregistry.iam.gserviceaccount.com
```
作成したサービスアカウントを変数に入力します。
```
export SERVICE_ACCOUNT=YOUR_SERVICE_ACCOUNT
```
次の手順に沿って KMS を使用して CMEK を作成するか、既存の KMS 鍵を使用します。CMEK 鍵は、ランタイムのロケーションと同じリージョンに存在する必要があります。
1. キーリングを作成する
```
gcloud kms keyrings create $KEY_RING_NAME \
  --location $RUNTIME_LOCATION \
  --project $PROJECT_ID
```
2. 鍵を作成します。
```
gcloud kms keys create $KEY_NAME \
  --keyring $KEY_RING_NAME \
  --location $RUNTIME_LOCATION \
  --purpose "encryption" \
  --project $PROJECT_ID
```
3. 鍵が作成されたことを確認します。鍵の作成が完了するまで数分かかることがあります。このコマンドで空のリストが返された場合は、しばらく待ってから再試行してください。鍵が表示されたら、次の手順に進みます。
```
gcloud kms keys list \
  --keyring $KEY_RING_NAME \
  --location $RUNTIME_LOCATION \
  --project $PROJECT_ID
```
  返される鍵は次のようになります。
```
projects/my-project/locations/us-west1/keyRings/my-key-ring-name/cryptoKeys/my-key-name
```
4. 作成した鍵を変数に挿入します。
```
export CMEK_KEY_ID=projects/PROJECT_ID/locations/RUNTIME_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME
```

CMEK でサービスアカウントに権限を付与します。

gcloud kms keys add-iam-policy-binding $KEY_NAME \
  --location $RUNTIME_LOCATION \
  --keyring $KEY_RING_NAME \
  --member serviceAccount:$SERVICE_ACCOUNT \
  --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
  --project $PROJECT_ID

サービスアカウントに CMEK に対する roles/cloudkms.cryptoKeyEncrypterDecrypter 権限があることを確認します。
```
gcloud kms keys get-iam-policy $CMEK_KEY_ID
```

ステップ 4: インスタンスを作成する

このセクションでは、API Hub のインスタンスを 1 つ作成します。プロジェクトごとに 1 つのインスタンスのみ使用できます。

リクエストの例

curl https://apigeeregistry.googleapis.com/v1/projects/$PROJECT_ID/locations/$RUNTIME_LOCATION/instances?instance_id=default \
  -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data-raw '{
    "config": {
      "cmek_key_name": "'"$CMEK_KEY_ID"'"
  }
}'

レスポンスの例

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-11T08:32:14.950522187Z",
    "target": "projects/my-project/locations/us-central1/instances/default",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

一般的なエラー - 不正な入力データ

HTTP ステータスコード:	`400 Bad Request`
エラーメッセージ:	`Instance is a singleton, and instance_id must be set to "default".`
考えられる原因:	`instance_id` を `default` 以外に設定します。
解決方法:	`default` を `instance_id` として使用します。

HTTP ステータスコード:	`400 Bad Request`
エラーメッセージ:	`global is not a supported location to create Instance.`
考えられる原因:	`global` を場所として設定しています。
解決方法:	上記のサポートされているランタイムロケーションのいずれかを使用します。

HTTP ステータスコード:	`401 Unauthorized`
エラーメッセージ:	`Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.`
考えられる原因:	無効な認証トークン。
解決方法:	リクエストトークンの形式が正しくないか、期限が切れている可能性があります。`token="$(gcloud auth print-access-token)"` を実行して認証トークンを再生成し、ヘッダーとして `Authorization: Bearer ${token}` を渡します。

HTTP ステータスコード:	`403 PERMISSION_DENIED`
エラーメッセージ:	`Location RUNTIME_LOCATION is not found or access is unauthorized.`
考えられる原因:	ロケーションをサポートされていないロケーションに設定しています。
解決方法:	上記のサポートされているランタイムロケーションのいずれかを使用します。

HTTP ステータスコード:	`400 Bad Request`
エラーメッセージ:	`Instance.config.cmek_key_name must be provided to create Instance.`
考えられる原因:	`cmek_key_name` はデータで提供されていません。
解決方法:	CMEK 名を指定します。詳しい手順については、サービスアカウントと CMEK を作成するをご覧ください。

HTTP ステータスコード:	`400 Bad Request`
エラーメッセージ:	`Invalid key format: a valid key should be in the form of projects/PROJECT/locations/us-central1/keyRings/KEYRING/cryptoKeys/CRYPTOKEY.`
考えられる原因:	`cmek_key_name` の形式が正しくありません。
解決方法:	鍵の形式を修正してください。

HTTP ステータスコード:	`400 Bad Request`
エラーメッセージ:	`CMEK key location needs to match the location of instance creation.`
考えられる原因:	CMEK は別の場所にあります。
解決方法:	CMEK の場所を修正します。

HTTP ステータスコード:	`400 Bad Request`
エラーメッセージ:	`Apigee Registry service account must have roles/cloudkms.cryptoKeyEncrypterDecrypter permission on the CMEK key.`
考えられる原因:	Apigee サービスアカウントに CMEK に対する権限がありません。わかるのは、サービスアカウントに必要な権限がないという点のみです。鍵がまったく存在しない可能性もありますが、判断することはできません。
解決方法:	鍵が存在し、その鍵に必要な権限が Apigee Registry サービスアカウントにあることを確認します。

一般的なエラー - 不正な状態

HTTP ステータスコード:	`400 Bad Request`
エラーメッセージ:	インスタンスがアクティブな状態である場合: `Instance is ACTIVE at SOME_LOCATION. It cannot be created again.` インスタンスがアクティブな状態でない場合: `Instance has state STATE at SOME_LOCATION. It cannot be created.`
考えられる原因:	インスタンスがすでに存在するか、どこかのロケーションで作成されている場合、この API を呼び出します。
解決方法:	この API が誤ってトリガーされた場合は、エラーを無視してください。これが正当な呼び出しで、実際にこのロケーションにインスタンスを作成する場合は、現在のインスタンスのロケーションで、まず `DeleteInstance` を呼び出します。

インスタンスの取得

このセクションでは、プロジェクトに関連付けられている API Hub ランタイムインスタンスの詳細（リージョン、状態など）を取得する方法について説明します。

リクエストの例

curl https://apigeeregistry.googleapis.com/v1/projects/$PROJECT_ID/locations/$RUNTIME_LOCATION/instances/default \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

レスポンスの例 - インスタンス作成中

{
  "name": "projects/my-project/locations/us-central1/instances/default",
  "createTime": "2022-03-11T08:32:14.944703257Z",
  "updateTime": "2022-03-11T08:32:14.944703257Z",
  "state": "CREATING",
  "stateMessage": "Creating instance...\nDetails: projects/PROJECT_ID/locations/RUNTIME_LOCATION/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "config": {
    "location": "us-central1",
    "cmekKeyName": "projects/PROJECT/locations/RUNTIME_LOCATION/keyRings/KEYRING/cryptoKeys/KEY""
  }
}

レスポンスの例 - インスタンス作成完了

{
  "name": "projects/myproject/locations/us-central1/instances/default",
  "createTime": "2022-03-11T08:32:14.944703257Z",
  "updateTime": "2022-03-11T08:56:31.087709218Z",
  "config": {
    "location": "us-central1",
    "cmekKeyName": "projects/my-project/locations/us-central1/keyRings/apihub-key-ring/cryptoKeys/apihub-key"
  },
  "state": "ACTIVE",
  "stateMessage": "Instance is active and ready to use."
}

一般的なエラー

HTTP ステータスコード:	`404 Not Found`
エラーメッセージ:	`Resource was not found.`
考えられる原因:	インスタンスが存在しないロケーションでこの API を呼び出す。
解決方法:	インスタンスを作成するロケーションで `GetInstance` API を呼び出す前に、`CreateInstance` API を呼び出します。インスタンスは作成されたがロケーションが不明な場合は、任意の場所で `CreateInstance` API を呼び出します。返ってくるエラーメッセージから、インスタンスのロケーションに関するヒントが得られます。

インスタンスの削除

このセクションでは、インスタンスを削除する方法について説明します。

注: DeleteInstance は長時間実行オペレーション（LRO）です。完了するまでに 10～15 秒かかります。DeleteInstance が呼び出されると、オペレーション ID が返されます。LRO のステータスを確認するには、オペレーション ID を使用して GetOperation を呼び出します。

リクエストの例

curl https://apigeeregistry.googleapis.com/v1/projects/$PROJECT_ID/locations/$RUNTIME_LOCATION/instances/default \
  -X DELETE \
  -H "Authorization: Bearer $TOKEN"

レスポンスの例

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-11T08:32:14.950522187Z",
    "target": "projects/my-project/locations/us-central1/instances/default",
    "verb": "delete",
    "apiVersion": "v1"
  },
  "done": false
}

一般的なエラー

HTTP ステータスコード:	`404 Not Found`
エラーメッセージ:	`Resource was not found.`
考えられる原因:	インスタンスが存在しないロケーションでこの API を呼び出す。
解決方法:	インスタンスが `ACTIVE` または `FAILED` であるロケーションでのみ `DeleteInstance` を呼び出します。

HTTP ステータスコード:	`400 Bad Request`
エラーメッセージ:	`Instance must be ACTIVE or FAILED to be deleted. Current state: STATE.`
考えられる原因:	インスタンスの状態が `ACTIVE` でも `FAILED` でもないロケーションで、この API を呼び出します。
解決方法:	インスタンスが `ACTIVE` または `FAILED` であるロケーションでのみ `DeleteInstance` を呼び出します。

オペレーションの取得

このセクションでは、オペレーションのステータスを確認する方法について説明します。オペレーションの完了に時間がかかる場合（LRO）、API からオペレーション ID が返されます。そのオペレーション ID を使用して GetOperation を呼び出すと、オペレーションのステータスが返されます。

リクエストの例

curl https://apigeeregistry.googleapis.com/v1/projects/$PROJECT_ID/locations/$RUNTIME_LOCATION/operations/OPERATION_ID \
  -X GET \
  -H "Authorization: Bearer $TOKEN"

ここで、OPERATION_ID はインスタンスの作成で説明した LRO について返される値です。形式は operation-1650479361714-5dd1a2c1068bf-464fac6b-18eeb734 です。

レスポンスの例 - インスタンス作成中

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-11T08:32:14.950522187Z",
    "target": "projects/my-project/locations/us-central1/instances/default",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

レスポンスの例 - インスタンス作成完了

{
  "name": "projects/my-project/locations/us-central1/operations/operation-1646987534895-5d9ed2af7889a-b4d376e8-14964abc",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-11T08:32:14.950522187Z",
    "endTime": "2022-03-11T08:56:31.069701960Z",
    "target": "projects/my-project/locations/us-central1/instances/default",
    "verb": "create",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.Instance",
    "name": "projects/my-project/locations/us-central1/instances/default",
    "createTime": "2022-03-11T08:32:14.944703257Z",
    "updateTime": "2022-03-11T08:56:31.069701960Z",
    "config": {
      "location": "us-central1",
      "cmekKeyName": ""projects/PROJECT/locations/RUNTIME_LOCATION/keyRings/KEYRING/cryptoKeys/KEY""
    },
    "state": "ACTIVE",
    "stateMessage": "Instance is active and ready to use."
  }
}

レスポンスの例 - インスタンス削除完了

{
  "name": "projects/my-project/locations/us-east1/operations/operation-1647669637561-5da8bfb743b86-4af586a4-83c04472",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigeeregistry.v1.OperationMetadata",
    "createTime": "2022-03-19T06:00:38.046462309Z",
    "endTime": "2022-03-19T06:01:01.382751041Z",
    "target": "projects/my-project/locations/us-east1/instances/default",
    "verb": "delete",
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.protobuf.Empty"
  }
}

次のステップ

API Hub の使用開始に関するヒントについては、次のステップをご覧ください。

CLI を使用して API Hub をプロビジョニングする

ステップの概要

ステップ 1: API を有効にする

コンソール

gcloud

ステップ 2: 環境変数を定義する

ステップ 3: サービス アカウントと CMEK を作成する

ステップ 4: インスタンスを作成する

リクエストの例

レスポンスの例

一般的なエラー - 不正な入力データ

一般的なエラー - 不正な状態

インスタンスの取得

リクエストの例

レスポンスの例 - インスタンス作成中

レスポンスの例 - インスタンス作成完了

一般的なエラー

インスタンスの削除

リクエストの例

レスポンスの例

一般的なエラー

オペレーションの取得

リクエストの例

レスポンスの例 - インスタンス作成中

レスポンスの例 - インスタンス作成完了

レスポンスの例 - インスタンス削除完了

次のステップ

ステップ 3: サービスアカウントと CMEK を作成する