Menyiapkan Cloud Endpoints OpenAPI untuk fungsi Cloud Run dengan ESPv2

Mencadangkan nama host Cloud Run

Anda harus mencadangkan nama host Cloud Run untuk layanan ESPv2 agar dapat mengonfigurasi dokumen OpenAPI atau konfigurasi layanan gRPC. Untuk mencadangkan nama host, Anda akan men-deploy container contoh ke Cloud Run. Selanjutnya, Anda akan men-deploy container ESPv2 ke layanan Cloud Run yang sama.

1. Pastikan gcloud CLI diizinkan untuk mengakses data dan layanan Anda.
   1. Log in.

      gcloud auth login

   2. Di tab browser baru yang terbuka, pilih akun yang memiliki peran Editor atau Pemilik di project yang Anda buat untuk men-deploy ESPv2 ke Cloud Run. Google Cloud
2. Tetapkan region.

   gcloud config set run/region us-central1

3. Deploy image contoh gcr.io/cloudrun/hello ke Cloud Run. Ganti CLOUD_RUN_SERVICE_NAME dengan nama yang ingin Anda gunakan untuk layanan.

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
       --image="gcr.io/cloudrun/hello" \
       --allow-unauthenticated \
       --platform managed \
       --project=ESP_PROJECT_ID
   

   Setelah berhasil diselesaikan, perintah akan menampilkan pesan yang mirip dengan berikut ini:

   Service [CLOUD_RUN_SERVICE_NAME] revision [CLOUD_RUN_SERVICE_NAME-REVISION_NUM] has been deployed and is serving traffic at CLOUD_RUN_SERVICE_URL

   Misalnya, jika Anda menetapkan CLOUD_RUN_SERVICE_NAME ke gateway:

   Service [gateway] revision [gateway-00001] has been deployed and is serving traffic at https://gateway-12345-uc.a.run.app

   Dalam contoh ini, https://gateway-12345-uc.a.run.app adalah CLOUD_RUN_SERVICE_URL dan gateway-12345-uc.a.run.app adalah CLOUD_RUN_HOSTNAME.

4. Catat CLOUD_RUN_SERVICE_NAME dan CLOUD_RUN_HOSTNAME. Selanjutnya, Anda akan men-deploy ESPv2 ke layanan Cloud Run CLOUD_RUN_SERVICE_NAME. Anda menentukan CLOUD_RUN_HOSTNAME di kolom host pada dokumen OpenAPI.

Mengonfigurasi Endpoint

Anda harus memiliki dokumen OpenAPI berdasarkan Spesifikasi OpenAPI v2.0 yang menjelaskan permukaan fungsi Anda dan persyaratan autentikasi apa pun. Anda juga perlu menambahkan kolom khusus Google yang berisi URL untuk setiap fungsi sehingga ESPv2 memiliki informasi yang diperlukan untuk memanggil fungsi. Jika Anda baru mengenal OpenAPI, lihat Ringkasan OpenAPI untuk mengetahui informasi selengkapnya

1. Buat file teks bernama openapi-functions.yaml. (Untuk memudahkan, halaman ini merujuk ke dokumen OpenAPI dengan nama file tersebut, tetapi Anda dapat menamainya dengan nama lain jika mau.)
2. Setiap fungsi Anda harus dicantumkan di bagian paths dalam file openapi-functions.yaml. Contoh:

   swagger: '2.0'
   info:
     title: Cloud Endpoints + GCF
     description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
     version: 1.0.0
   host: HOST
   schemes:
     - https
   produces:
     - application/json
   paths:
     /hello:
       get:
         summary: Greet a user
         operationId: hello
         x-google-backend:
           address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
           protocol: h2
         responses:
           '200':
             description: A successful response
             schema:
               type: string

   Indentasi penting untuk format yaml. Misalnya, kolom host harus berada di tingkat yang sama dengan info.
3. Di kolom address di bagian x-google-backend, ganti REGION dengan Google Cloud region tempat fungsi Anda berada, FUNCTIONS_PROJECT_ID dengan Google Cloud project ID Anda dan FUNCTIONS_NAME dengan nama fungsi Anda. Contoh:

   x-google-backend:
     address: https://us-central1-myproject.cloudfunctions.net/helloGET

   Jika Anda ingin mengamankan fungsi Cloud Run dengan hanya mengizinkan ESPv2 memanggilnya, pastikan kolom address menyertakan nama fungsi jika jwt_audience tidak ditentukan. Contoh:

   x-google-backend:
     address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
     path_translation: CONSTANT_ADDRESS

   Jika jwt_audience ditentukan, nilainya juga harus menyertakan nama fungsi. Contoh:

   x-google-backend:
     address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net
     jwt_audience: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME
     path_translation: APPEND_PATH_TO_ADDRESS

   ESPv2 membuat token ID saat memanggil fungsi Cloud Run untuk autentikasi. Token ID harus memiliki audience yang tepat yang menentukan host fungsi dan nama fungsi. ESPv2 menetapkan audience untuk token ID menggunakan nilai di kolom jwt_audience jika ditentukan, atau menggunakan kolom address.

4. Di kolom host, tentukan CLOUD_RUN_HOSTNAME, bagian nama host dari URL yang dicadangkan di atas dalam Mencadangkan nama host Cloud Run. Jangan sertakan ID protokol, https://. Contoh:

   swagger: '2.0'
     info:
       title: Cloud Endpoints + GCF
       description: Sample API on Cloud Endpoints with a Google Cloud Functions backend
       version: 1.0.0
     host: gateway-12345-uc.a.run.app

5. Perhatikan nilai properti title dalam file openapi-functions.yaml:

   title: Cloud Endpoints + GCF

   Nilai properti title menjadi nama layanan Endpoints setelah Anda men-deploy konfigurasi.

6. Simpan dokumen OpenAPI Anda.

Untuk mengetahui informasi tentang kolom dalam dokumen OpenAPI yang diperlukan Endpoints, lihat Mengonfigurasi Endpoints.

Men-deploy konfigurasi Endpoint

Untuk men-deploy konfigurasi Endpoints, Anda menggunakan perintah gcloud endpoints services deploy. Perintah ini menggunakan Service Management untuk membuat layanan terkelola.

Untuk men-deploy konfigurasi Endpoints:

1. Pastikan Anda berada di direktori yang berisi dokumen OpenAPI.

2. Upload konfigurasi dan buat layanan terkelola.

   gcloud endpoints services deploy openapi-functions.yaml \
       --project ESP_PROJECT_ID

   Tindakan ini akan membuat layanan Endpoints baru dengan nama yang Anda tentukan di kolom host pada file openapi-functions.yaml. Layanan dikonfigurasi sesuai dengan dokumen OpenAPI Anda.

   Saat membuat dan mengonfigurasi layanan, Service Management akan menampilkan informasi ke terminal. Setelah deployment selesai, pesan yang mirip dengan berikut akan ditampilkan:

   Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]

   CONFIG_ID adalah ID konfigurasi layanan Endpoints unik yang dibuat oleh deployment. Contoh:

   Service Configuration [2019-02-01r0] uploaded for service [gateway-12345-uc.a.run.app]

   ID konfigurasi layanan terdiri dari stempel tanggal diikuti dengan nomor revisi. Jika Anda men-deploy openapi-functions.yaml lagi pada hari yang sama, nomor revisi akan bertambah dalam ID konfigurasi layanan. Anda dapat melihat konfigurasi layanan dan histori deployment di halaman Endpoints > Services di konsol Google Cloud .

   Jika Anda menerima pesan error, lihat Memecahkan masalah deployment konfigurasi Endpoints.

Memeriksa layanan yang diperlukan

Dalam sebagian besar kasus, perintah gcloud endpoints services deploy akan mengaktifkan layanan yang diperlukan ini. Namun, perintah gcloud berhasil diselesaikan, tetapi tidak mengaktifkan layanan yang diperlukan dalam keadaan berikut:

• Jika Anda menggunakan aplikasi pihak ketiga seperti Terraform, dan Anda tidak menyertakan layanan ini.

• Anda men-deploy konfigurasi Endpoints ke projectGoogle Cloud yang sudah ada tempat layanan ini dinonaktifkan secara eksplisit.

Gunakan perintah berikut untuk mengonfirmasi bahwa layanan yang diperlukan sudah diaktifkan:

gcloud services list

Jika Anda tidak melihat layanan yang diperlukan tercantum, aktifkan layanan tersebut:

gcloud services enable servicemanagement.googleapis.com
gcloud services enable servicecontrol.googleapis.com

Aktifkan juga layanan Endpoints Anda:

gcloud services enable ENDPOINTS_SERVICE_NAME

Untuk menentukan ENDPOINTS_SERVICE_NAME, Anda dapat:

• Setelah men-deploy konfigurasi Endpoints, buka halaman Endpoints di Konsol Cloud. Daftar ENDPOINTS_SERVICE_NAME yang mungkin ditampilkan di kolom Nama layanan.

• Untuk OpenAPI, ENDPOINTS_SERVICE_NAME adalah yang Anda tentukan di kolom host spesifikasi OpenAPI. Untuk gRPC, ENDPOINTS_SERVICE_NAME adalah yang Anda tentukan di kolom name konfigurasi gRPC Endpoints.

Untuk mengetahui informasi selengkapnya tentang perintah gcloud, lihat layanan gcloud.

Membangun image ESPv2 baru

Buat konfigurasi layanan Endpoints menjadi image Docker ESPv2 baru. Anda akan men-deploy image ini ke layanan Cloud Run yang dicadangkan nanti.

Untuk membuat konfigurasi layanan menjadi image Docker ESPv2 baru:

1. Download skrip ini ke komputer lokal Anda tempat gcloud CLI diinstal.

2. Jalankan skrip dengan perintah berikut:

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s CLOUD_RUN_HOSTNAME \
       -c CONFIG_ID -p ESP_PROJECT_ID

   Untuk CLOUD_RUN_HOSTNAME, tentukan nama host URL yang Anda pesan di atas dalam Memesan nama host Cloud Run. Jangan sertakan ID protokol, https://.

   Contoh:

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s gateway-12345-uc.a.run.app \
       -c 2019-02-01r0 -p your-project-id

3. Skrip menggunakan perintah gcloud untuk mendownload konfigurasi layanan, membangun konfigurasi layanan menjadi image ESPv2 baru, dan mengupload image baru ke container registry project Anda. Skrip otomatis menggunakan rilis ESPv2 terbaru, yang ditunjukkan oleh ESP_VERSION dalam nama gambar output. Gambar output diupload ke:

   gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID

   Contoh:

   gcr.io/your-project-id/endpoints-runtime-serverless:2.14.0-gateway-12345-uc.a.run.app-2019-02-01r0"

Men-deploy container ESPv2

1. Deploy layanan Cloud Run ESPv2 dengan image baru yang Anda buat di atas. Ganti CLOUD_RUN_SERVICE_NAME dengan nama layanan Cloud Run yang sama dengan yang Anda gunakan saat pertama kali mencadangkan nama host di atas dalam Mencadangkan nama host Cloud Run:

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --allow-unauthenticated \
     --platform managed \
     --project=ESP_PROJECT_ID

2. Jika ingin mengonfigurasi Endpoints untuk menggunakan opsi startup ESPv2 tambahan, seperti mengaktifkan CORS, Anda dapat meneruskan argumen dalam variabel lingkungan ESPv2_ARGS:

   gcloud run deploy CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESP_PROJECT_ID/endpoints-runtime-serverless:ESP_VERSION-CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
     --allow-unauthenticated \
     --platform managed \
     --project ESP_PROJECT_ID

   Untuk mengetahui informasi dan contoh selengkapnya tentang cara menyetel variabel lingkungan ESPv2_ARGS, termasuk daftar opsi yang tersedia dan informasi tentang cara menentukan beberapa opsi, lihat Flag Beta Extensible Service Proxy V2.

3. Memberikan izin ESPv2 untuk memanggil Service Management dan Service Control.

• Di konsol Google Cloud , buka halaman Cloud Run.

Buka halaman Cloud Run

• Anda dapat melihat instance Cloud Run yang di-deploy dan akun layanan yang terkait dengannya.
• Berikan izin yang diperlukan ke akun layanan:

gcloud projects add-iam-policy-binding PROJECT_NAME \
   --member "serviceAccount:SERVICE_ACCOUNT" \
   --role roles/servicemanagement.serviceController

Untuk mengetahui informasi selengkapnya, lihat Apa yang dimaksud dengan peran dan izin?

4. Beri ESPv2 izin untuk memanggil fungsi Anda. Jalankan perintah berikut untuk setiap fungsi. Dalam perintah berikut:

   • Ganti FUNCTION_NAME dengan nama fungsi Anda dan FUNCTION_REGION dengan region tempat fungsi di-deploy. Jika Anda menggunakan fungsi yang dibuat di Panduan memulai: Menggunakan Google Cloud CLI, maka gunakan helloGET sebagai nama.
   • Ganti ESP_PROJECT_NUMBER dengan nomor project yang Anda buat untuk ESPv2. Salah satu cara untuk menemukannya adalah dengan membuka halaman IAM di konsol Google Cloud dan menemukan Akun layanan komputasi default, yang merupakan akun layanan yang digunakan dalam flag member.

   gcloud functions add-iam-policy-binding FUNCTION_NAME \
      --region FUNCTION_REGION \
      --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
      --role "roles/cloudfunctions.invoker" \
      --project FUNCTIONS_PROJECT_ID
   

Untuk mengetahui informasi selengkapnya, lihat Mengelola Akses melalui IAM.

Mengirim permintaan ke API

Bagian ini menunjukkan cara mengirim permintaan ke API Anda.

1. Buat variabel lingkungan untuk nama layanan Endpoints Anda. Ini adalah nama yang Anda tentukan di kolom host pada dokumen OpenAPI Anda. Misalnya:

   • Linux atau macOS:

     export ENDPOINTS_HOST=gateway-12345-uc.a.run.app

   • Windows PowerShell:

     $Env: ENDPOINTS_HOST="gateway-12345-uc.a.run.app"

curl --request GET \
   --header "content-type:application/json" \
   "https://${ENDPOINTS_HOST}/hello"

(Invoke-WebRequest -Method GET `
    -Headers @{"content-type"="application/json"} `
    -URI "https://$Env:ENDPOINTS_HOST/hello").Content

Jika Anda tidak mendapatkan respons yang berhasil, lihat Memecahkan Masalah Error Respons.

Anda baru saja men-deploy dan menguji API di Endpoints.

Melacak aktivitas API

1. Lihat grafik aktivitas untuk API Anda di halaman Endpoints > Service di konsol Google Cloud .

   Melihat grafik aktivitas Endpoint

   Mungkin perlu waktu beberapa saat agar permintaan ditampilkan dalam grafik.

2. Lihat log permintaan untuk API Anda di halaman Logs Explorer. Melihat log permintaan Endpoints