Hub API penyediaan menggunakan CLI

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Bagian ini menjelaskan cara menyediakan hub API menggunakan command line.

Ringkasan langkah

Langkah-langkah penyediaannya adalah sebagai berikut:

Pastikan Anda telah memenuhi prasyarat hub API.
Langkah 1: Aktifkan API. Apigee mengharuskan Anda mengaktifkan beberapa API Google Cloud.
Langkah 2: Tentukan variabel lingkungan. Variabel lingkungan membantu memastikan konsistensi saat menjalankan perintah.
Langkah 3: Buat akun layanan dan CMEK. Akun layanan ini digunakan oleh library klien Google Cloud untuk melakukan autentikasi dengan Google Cloud API. Karena informasi tentang API internal dapat dianggap sensitif, Apigee memerlukan CMEK untuk mengenkripsi dan mendekripsi (melindungi) data dalam penyimpanan. CMEK harus berada di region yang sama dengan lokasi instance.
Langkah 4: Buat instance. Instance adalah tempat project Anda dan layanan terkait disimpan.
Periksa status instance (opsional). Karena perlu waktu beberapa saat untuk membuat instance, gunakan perintah ini untuk memeriksa statusnya.
Hapus instance (opsional). Gunakan perintah ini jika Anda perlu menghapus instance.
Periksa status operasi (opsional). Gunakan perintah ini untuk memeriksa status operasi yang berjalan lama.

Langkah 1: Aktifkan API

Untuk menggunakan hub API, Anda harus mengaktifkan API berikut untuk project:

Apigee Registry API: Hub API berinteraksi dengan Registry API untuk melihat dan mengelola API organisasi Anda.
Cloud Key Management Service (KMS) API: Memungkinkan pelanggan mengelola kunci enkripsi dan melakukan operasi kriptografis dengan kunci tersebut.
Service Usage API: Mengaktifkan layanan yang ingin digunakan konsumen layanan di Google Cloud Platform, mencantumkan layanan yang tersedia atau diaktifkan, atau menonaktifkan layanan yang tidak lagi digunakan konsumen layanan.

Anda dapat menggunakan UI Google Cloud Console atau CLI untuk mengaktifkan API.

Konsol

Untuk mengaktifkan API menggunakan UI, lakukan langkah-langkah berikut di Konsol Google Cloud:

Aktifkan Apigee Registry API:

Buka Enable Apigee Registry API

Klik Enable.

Google Cloud akan mengaktifkan API untuk project Google Cloud Anda.
Aktifkan Cloud Key Management Service (KMS) API:

Buka Enable Cloud KMS API

Klik Enable.

Google Cloud akan mengaktifkan API untuk project Google Cloud Anda.
Aktifkan Service Usage API:
Buka Enable Service Usage API

Klik Enable.

Google Cloud akan mengaktifkan API untuk project Google Cloud Anda.
Untuk mengonfirmasi bahwa Anda telah mengaktifkan API:
Buka Enabled APIs & Services

API yang baru saja Anda tambahkan ditampilkan dalam daftar API yang telah diaktifkan:
- API Registry Apigee
- API Cloud Key Management Service (KMS)
- Service Usage API

gcloud

Jalankan perintah berikut:

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

Dengan PROJECT_ID adalah nama project Konsol Google Cloud Anda.

(Opsional) Untuk memeriksa pekerjaan Anda, gunakan perintah services list untuk menampilkan semua API yang diaktifkan:
```
gcloud services list
```
Respons akan menampilkan semua layanan yang diaktifkan, termasuk API yang baru saja Anda aktifkan.

Langkah 2: Menentukan variabel lingkungan

Menggunakan variabel lingkungan akan memastikan konsistensi dan memudahkan Anda untuk mengikuti dokumentasi pada langkah-langkah selanjutnya.

Tentukan variabel lingkungan berikut, dengan mengganti variabel dinamis dengan nilai sebenarnya:
```
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
```
Dengan keterangan:
- TOKEN adalah token yang mengautentikasi dan memberi otorisasi panggilan ke Apigee Registry API. Token tersebut harus diteruskan di header Authentication sebagai token pemilik. Perlu diperhatikan bahwa masa berlaku token berakhir setelah jangka waktu tertentu, dan jika token valid, Anda cukup membuatnya kembali menggunakan perintah yang sama. Untuk mengetahui informasi selengkapnya, lihat halaman referensi untuk perintah print-access-token.
- KEY_RING_NAME adalah nama key ring yang akan Anda gunakan untuk mengidentifikasi key ring enkripsi Anda.
- KEY_NAME adalah nama kunci yang akan Anda gunakan untuk mengidentifikasi kunci enkripsi hub API.
- PROJECT_ID adalah project ID Cloud yang Anda buat sebagai bagian dari Prasyarat.
- RUNTIME_LOCATION adalah lokasi fisik tempat instance Apigee Registry yang akan Anda buat nanti. Kunci CMEK harus berada di region yang sama dengan lokasi runtime.
  
  Catatan:
  Untuk RUNTIME_LOCATION, pastikan Anda menggunakan nama region, bukan nama zona. Misalnya, us-west1 adalah nama region, sedangkan us-west1-a adalah zona dalam region tersebut. Lihat juga Mengidentifikasi region atau zona.
  
  Untuk mengetahui daftar lokasi runtime yang tersedia, lihat Lokasi Apigee.
- CMEK_KEY_ID adalah ID kunci dari kunci enkripsi yang dikelola pelanggan. Rotasi kunci saat ini tidak didukung.
  
  ID kunci memiliki sintaksis berikut (serupa dengan jalur file):
```
projects/PROJECT_ID/locations/RUNTIME_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME
```
(Opsional) Periksa pekerjaan Anda dengan menjalankan echo nilai yang baru saja Anda tetapkan. Perhatikan bahwa jika Anda ingin menggunakan variabel dalam perintah, tambahkan tanda dolar ($) di awal nama variabel.
```
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
```

Langkah 3: Buat akun layanan dan CMEK

Bagian ini menjelaskan cara membuat akun layanan serta key ring dan kunci enkripsi.

Buat akun layanan per produk per project Apigee Registry untuk project Anda:

Catatan: Anda dapat menjalankan perintah ini beberapa kali meskipun akun layanan sudah dibuat.
```
gcloud beta services identity create --service=apigeeregistry.googleapis.com --project=$PROJECT_ID
```
Akun layanan yang ditampilkan mirip dengan yang berikut ini:
```
service-755582297973@gcp-sa-apigeeregistry.iam.gserviceaccount.com
```
Masukkan akun layanan yang dibuat dalam variabel:
```
export SERVICE_ACCOUNT=YOUR_SERVICE_ACCOUNT
```

Buat CMEK menggunakan KMS dengan mengikuti langkah-langkah di bawah ini atau gunakan kunci KMS yang ada. Kunci CMEK harus berada di region yang sama dengan lokasi runtime.

Buat keyring:

gcloud kms keyrings create $KEY_RING_NAME \
  --location $RUNTIME_LOCATION \
  --project $PROJECT_ID

Buat kunci:

gcloud kms keys create $KEY_NAME \
  --keyring $KEY_RING_NAME \
  --location $RUNTIME_LOCATION \
  --purpose "encryption" \
  --project $PROJECT_ID

Verifikasi bahwa kunci telah dibuat. Mungkin perlu waktu beberapa menit untuk membuat kunci. Jika perintah ini menampilkan daftar kosong, tunggu dan coba lagi. Saat kunci muncul, Anda dapat melanjutkan ke langkah berikutnya:
```
gcloud kms keys list \
  --keyring $KEY_RING_NAME \
  --location $RUNTIME_LOCATION \
  --project $PROJECT_ID
```
Kunci yang ditampilkan mirip dengan yang berikut ini:
```
projects/my-project/locations/us-west1/keyRings/my-key-ring-name/cryptoKeys/my-key-name
```

Masukkan kunci yang dibuat dalam variabel:

export CMEK_KEY_ID=projects/PROJECT_ID/locations/RUNTIME_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME

Berikan izin untuk akun layanan di 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

Pastikan akun layanan Anda memiliki izin roles/cloudkms.cryptoKeyEncrypterDecrypter di CMEK.
```
gcloud kms keys get-iam-policy $CMEK_KEY_ID
```

Langkah 4: Buat instance

Di bagian ini, Anda akan membuat satu instance hub API. Hanya boleh ada satu instance per project.

Permintaan sampel

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"'"
  }
}'

Contoh respons

{
  "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
}

Kesalahan umum - data input buruk

Kode status HTTP:	`400 Bad Request`
Pesan error:	`Instance is a singleton, and instance_id must be set to "default".`
Penyebab yang mungkin:	Menyetel `instance_id` ke selain `default`.
Solusi:	Gunakan `default` sebagai `instance_id` Anda.

Kode status HTTP:	`400 Bad Request`
Pesan error:	`global is not a supported location to create Instance.`
Penyebab yang mungkin:	Menyetel `global` sebagai lokasi.
Solusi:	Gunakan salah satu lokasi runtime yang didukung dan tercantum di atas.

Kode status HTTP:	`401 Unauthorized`
Pesan error:	`Request had invalid authentication credentials. Expected OAuth 2 access token, login cookie or other valid authentication credential.`
Penyebab yang mungkin:	Token Autentikasi Inavlid.
Solusi:	Token permintaan mungkin salah format atau sudah tidak berlaku. Buat ulang token autentikasi dengan menjalankan `token="$(gcloud auth print-access-token)"` dan teruskan `Authorization: Bearer ${token}` sebagai header.

Kode status HTTP:	`403 PERMISSION_DENIED`
Pesan error:	`Location RUNTIME_LOCATION is not found or access is unauthorized.`
Penyebab yang mungkin:	Menyetel lokasi ke lokasi yang tidak didukung.
Solusi:	Gunakan salah satu lokasi runtime yang didukung dan tercantum di atas.

Kode status HTTP:	`400 Bad Request`
Pesan error:	`Instance.config.cmek_key_name must be provided to create Instance.`
Penyebab yang mungkin:	`cmek_key_name` tidak disediakan dalam data.
Solusi:	Beri nama CMEK. Lihat Membuat akun layanan dan CMEK untuk mendapatkan petunjuk mendetail.

Kode status HTTP:	`400 Bad Request`
Pesan error:	`Invalid key format: a valid key should be in the form of projects/PROJECT/locations/us-central1/keyRings/KEYRING/cryptoKeys/CRYPTOKEY.`
Penyebab yang mungkin:	`cmek_key_name` tidak diformat dengan benar.
Solusi:	Perbaiki format kunci.

Kode status HTTP:	`400 Bad Request`
Pesan error:	`CMEK key location needs to match the location of instance creation.`
Penyebab yang mungkin:	CMEK berada di lokasi yang berbeda.
Solusi:	Memperbaiki lokasi CMEK.

Kode status HTTP:	`400 Bad Request`
Pesan error:	`Apigee Registry service account must have roles/cloudkms.cryptoKeyEncrypterDecrypter permission on the CMEK key.`
Penyebab yang mungkin:	Akun layanan Apigee tidak memiliki izin di CMEK. Perhatikan bahwa kita hanya mengetahui bahwa akun layanan tidak memiliki izin yang diperlukan. Mungkin kunci tersebut tidak ada sama sekali, tetapi kami tidak tahu.
Solusi:	Pastikan kunci tersebut ada dan akun layanan Apigee Registry memiliki izin yang diperlukan pada kunci tersebut.

Error umum - kondisi buruk

Kode status HTTP:	`400 Bad Request`
Pesan error:	Jika instance aktif: `Instance is ACTIVE at SOME_LOCATION. It cannot be created again.` Jika instance bukan status aktif: `Instance has state STATE at SOME_LOCATION. It cannot be created.`
Penyebab yang mungkin:	Memanggil API ini ketika instance sudah ada atau dibuat di beberapa lokasi.
Solusi:	Abaikan error jika API ini tidak sengaja dipicu. Jika ini adalah panggilan yang sah dan Anda memang ingin membuat instance di lokasi ini, panggil `DeleteInstance` terlebih dahulu di lokasi instance saat ini.

Mendapatkan instance

Bagian ini menjelaskan cara mendapatkan detail (region, status, dll.) tentang Instance Runtime hub API yang terkait dengan project Anda.

Permintaan sampel

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

Contoh respons - pembuatan instance sedang berlangsung

{
  "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""
  }
}

Contoh respons - pembuatan instance selesai

{
  "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."
}

Error yang biasa terjadi

Kode status HTTP:	`404 Not Found`
Pesan error:	`Resource was not found.`
Penyebab yang mungkin:	Memanggil API ini di lokasi tempat instance tidak ada.
Solusi:	Panggil `CreateInstance` API sebelum memanggil `GetInstance` API di lokasi tempat Anda ingin membuat Instance. Jika Instance telah dibuat tetapi Anda tidak tahu lokasinya, panggil `CreateInstance` API di lokasi mana pun, yang akan gagal dengan pesan yang memberikan petunjuk tentang lokasi Instance.

Hapus instance

Bagian ini menjelaskan cara menghapus instance.

Catatan: DeleteInstance adalah Operasi yang Berjalan Lama (LRO); prosesnya memerlukan waktu 10-15 detik. Jika dipanggil, DeleteInstance akan menampilkan ID operasi. Untuk memeriksa status LRO, panggil GetOperation menggunakan ID operasi.

Permintaan sampel

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

Contoh respons

{
  "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
}

Error yang biasa terjadi

Kode status HTTP:	`404 Not Found`
Pesan error:	`Resource was not found.`
Penyebab yang mungkin:	Memanggil API ini di lokasi tempat instance tidak ada.
Solusi:	Panggil `DeleteInstance` hanya di lokasi tempat instance adalah `ACTIVE` atau `FAILED`.

Kode status HTTP:	`400 Bad Request`
Pesan error:	`Instance must be ACTIVE or FAILED to be deleted. Current state: STATE.`
Penyebab yang mungkin:	Memanggil API ini di lokasi yang status instance-nya bukan `ACTIVE` atau `FAILED`.
Solusi:	Panggil `DeleteInstance` hanya di lokasi tempat instance adalah `ACTIVE` atau `FAILED`.

Mendapatkan operasi

Bagian ini menjelaskan cara memeriksa status operasi. Jika operasi memerlukan waktu lama (LRO), API akan menampilkan ID operasi. Memanggil GetOperation menggunakan ID operasi akan menampilkan status operasi.

Permintaan sampel

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

Dengan OPERATION_ID adalah nilai yang ditampilkan untuk LRO seperti yang dijelaskan dalam Membuat instance, dan dalam bentuk operation-1650479361714-5dd1a2c1068bf-464fac6b-18eeb734.

Contoh respons - pembuatan instance sedang berlangsung

{
  "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
}

Contoh respons - pembuatan instance selesai

{
  "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."
  }
}

Contoh respons - penghapusan instance selesai

{
  "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"
  }
}

Langkah berikutnya

Lihat Langkah berikutnya untuk mendapatkan beberapa tips tentang cara memulai menggunakan hub API.