Hub API penyediaan menggunakan CLI

Halaman ini berlaku untuk Apigee dan Apigee Hybrid.

Pratinjau — Apigee API hub

Fitur ini tunduk pada "Persyaratan Penawaran Pra-GA" di bagian Persyaratan Layanan Umum dalam Persyaratan Khusus Layanan. Fitur pra-GA tersedia "sebagaimana adanya" dan mungkin memiliki dukungan terbatas. Untuk mengetahui informasi selengkapnya, lihat deskripsi tahap peluncuran.

Bagian ini menjelaskan cara menyediakan hub API menggunakan command line.

Izin yang diperlukan: Anda harus memiliki izin administrator untuk menyediakan hub API. Lihat Menyiapkan izin IAM untuk mengetahui petunjuknya.

Tips: Tunggu sekitar satu jam untuk menyediakan hub API.

Ringkasan langkah

Langkah-langkah penyediaannya adalah sebagai berikut:

1. Pastikan Anda telah memenuhi prasyarat hub API.
2. Langkah 1: Aktifkan API. Apigee mengharuskan Anda mengaktifkan beberapa API Google Cloud.
3. Langkah 2: Tentukan variabel lingkungan. Variabel lingkungan membantu memastikan konsistensi saat menjalankan perintah.
4. 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.
5. Langkah 4: Buat instance. Instance adalah tempat project Anda dan layanan terkait disimpan.
6. Periksa status instance (opsional). Karena perlu waktu beberapa saat untuk membuat instance, gunakan perintah ini untuk memeriksa statusnya.
7. Hapus instance (opsional). Gunakan perintah ini jika Anda perlu menghapus instance.
8. 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:

1. Aktifkan Apigee Registry API:

   Buka Enable Apigee Registry API

   Klik Enable.

   Google Cloud akan mengaktifkan API untuk project Google Cloud Anda.

2. Aktifkan Cloud Key Management Service (KMS) API:

   Buka Enable Cloud KMS API

   Klik Enable.

   Google Cloud akan mengaktifkan API untuk project Google Cloud Anda.

3. Aktifkan Service Usage API:

   Buka Enable Service Usage API

   Klik Enable.

   Google Cloud akan mengaktifkan API untuk project Google Cloud Anda.

4. 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

1. 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.

2. (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.

1. 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

2. (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.

1. 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:

   [e-mail]
   

2. Masukkan akun layanan yang dibuat dalam variabel:

   export SERVICE_ACCOUNT=YOUR_SERVICE_ACCOUNT
   

3. 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.

   1. Buat keyring:

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

   2. Buat kunci:

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

   3. 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
      

   4. Masukkan kunci yang dibuat dalam variabel:

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

4. 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
   
   

5. 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.

Catatan: CreateInstance adalah operasi yang berjalan lama (LRO); memerlukan waktu 30-45 menit untuk menyelesaikannya. Hub API memiliki arsitektur multi-tenant tunggal. Selama waktu ini, hub API menampilkan infrastruktur sehingga Anda dapat mulai menggunakan hub API.

Jika dipanggil, CreateInstance 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?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.