Menyiapkan Cloud Endpoints OpenAPI untuk lingkungan standar dengan ESPv2

Mengonfigurasi IAP untuk mengamankan aplikasi Anda

Untuk mengamankan aplikasi App Engine, Anda harus menggunakan Identity Aware Proxy (IAP) untuk memastikan bahwa permintaan diautentikasi.

Ikuti langkah-langkah untuk Mengaktifkan IAP, dan pastikan Anda dapat login ke aplikasi.

Selain itu, saat mengonfigurasi klien OAuth, catat client_id OAuth, yang disebut sebagai IAP_CLIENT_ID dalam tutorial ini.

Mencadangkan nama host Cloud Run

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

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

      gcloud auth login

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

   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, 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. Kemudian, Anda 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 platform aplikasi Anda dan persyaratan autentikasi apa pun. Anda juga perlu menambahkan kolom khusus Google yang berisi URL untuk setiap aplikasi sehingga ESPv2 memiliki informasi yang diperlukan untuk memanggil aplikasi. Jika Anda baru menggunakan OpenAPI, lihat ringkasan OpenAPI untuk mengetahui informasi selengkapnya

1. Buat file teks bernama openapi-appengine.yaml. (Untuk memudahkan, halaman ini merujuk pada dokumen OpenAPI dengan nama file tersebut, tetapi Anda bisa memberinya nama lain jika mau.)
2. Aplikasi backend App Engine Anda ditentukan di bagian atas file openapi-appengine.yaml, dalam definisi x-google-backend. Contoh:

     swagger: '2.0'
     info:
       title: Cloud Endpoints + App Engine
       description: Sample API on Cloud Endpoints with an App Engine backend
       version: 1.0.0
     host: CLOUD_RUN_HOSTNAME
     schemes:
       - https
     produces:
       - application/json
     x-google-backend:
       address: https://APP_PROJECT_ID.REGION.r.appspot.com
       jwt_audience: IAP_CLIENT_ID
       protocol: h2
     paths:
       /:
         get:
           summary: Greet a user
           operationId: hello
           responses:
             '200':
               description: A successful response
               schema:
                 type: string
   

   Indentasi penting untuk format yaml. Misalnya, kolom host harus berada pada level yang sama dengan info.
3. Pada kolom address di bagian x-google-backend, ganti APP_PROJECT_ID dengan project ID Google Cloud Anda, REGION dengan region GCP tempat Anda men-deploy App Engine, dan IAP_CLIENT_ID dengan Client ID OAuth yang Anda buat saat menyiapkan IAP.

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

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

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

   title: Cloud Endpoints + App Engine

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

6. Simpan dokumen OpenAPI Anda.

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

Men-deploy konfigurasi Endpoint

Untuk men-deploy konfigurasi Endpoint, gunakan perintah gcloud endpoints services deploy. Perintah ini menggunakan Pengelolaan Layanan untuk membuat layanan terkelola.

Untuk men-deploy konfigurasi Endpoint:

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

2. Mengupload konfigurasi dan membuat layanan terkelola.

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

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

   Saat membuat dan mengonfigurasi layanan, Pengelolaan Layanan menghasilkan informasi ke terminal. Setelah deployment selesai, pesan yang mirip dengan yang berikut ini akan ditampilkan:

   Service Configuration [CONFIG_ID] uploaded for service [CLOUD_RUN_HOSTNAME]

   CONFIG_ID adalah ID konfigurasi layanan Endpoint 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 yang diikuti dengan nomor revisi. Jika Anda men-deploy openapi-appengine.yaml lagi pada hari yang sama, nomor revisi akan bertambah di ID konfigurasi layanan. Anda dapat melihat konfigurasi layanan dan histori deployment di halaman Endpoint > Services di Konsol Google Cloud.

   Jika Anda mendapatkan pesan error, lihat Memecahkan masalah deployment konfigurasi Endpoint.

Memeriksa layanan yang diperlukan

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

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

• Anda telah men-deploy konfigurasi Endpoint ke project Google Cloud yang ada, yang menonaktifkan layanan ini secara eksplisit.

Gunakan perintah berikut untuk mengonfirmasi bahwa layanan yang diperlukan telah 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
gcloud services enable endpoints.googleapis.com

Aktifkan juga layanan Endpoint Anda:

gcloud services enable ENDPOINTS_SERVICE_NAME

Untuk menentukan ENDPOINTS_SERVICE_NAME, Anda dapat:

• Setelah men-deploy konfigurasi Endpoint, buka halaman Endpoint di Cloud Console. Daftar kemungkinan ENDPOINTS_SERVICE_NAME ditampilkan di bawah kolom Service name.

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

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

Membuat gambar ESPv2 baru

Build konfigurasi layanan Endpoint ke image Docker ESPv2 baru. Anda nanti akan men-deploy image ini ke layanan Cloud Run yang dicadangkan.

Untuk mem-build konfigurasi layanan ke dalam image docker ESPv2 baru:

1. Download skrip ini ke mesin lokal 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 cadangkan di atas di Pemesanan 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 ini menggunakan perintah gcloud untuk mendownload konfigurasi layanan, mem-build konfigurasi layanan ke image ESPv2 yang baru, dan mengupload image baru ke container registry project Anda. Skrip secara otomatis menggunakan rilis terbaru ESPv2, yang dilambangkan dengan ESP_VERSION dalam nama image 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 ESPv2 Cloud Run dengan image baru yang Anda build di atas. Ganti CLOUD_RUN_SERVICE_NAME dengan nama layanan Cloud Run yang sama seperti yang Anda gunakan saat pertama kali mencadangkan nama host di atas di bagian Memesan 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 Anda ingin mengonfigurasi Endpoint 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 menetapkan variabel lingkungan ESPv2_ARGS, termasuk daftar opsi yang tersedia dan informasi tentang cara menentukan beberapa opsi, lihat tanda Extensible Service Proxy V2.

3. Beri ESPv2 izin untuk memanggil aplikasi yang diamankan oleh IAP. Jalankan perintah berikut untuk setiap layanan. Dalam perintah berikut:
   • Ganti APP_PROJECT_ID dengan nama project ID App Engine Anda.
   • Ganti ESP_PROJECT_NUMBER dengan nomor project yang Anda buat untuk ESPv2. Salah satu cara untuk menemukannya adalah dengan membuka IAM console dan temukan akun layanan default Compute Engine, yang merupakan akun layanan yang digunakan dalam flag `member`.

     gcloud projects add-iam-policy-binding APP_PROJECT_ID \
         --member "serviceAccount:ESP_PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
         --role "roles/iap.httpsResourceAccessor"
       

Untuk mengetahui informasi selengkapnya, lihat Mengelola Akses menggunakan IAM.

Mengirim permintaan ke API

Bagian ini menunjukkan cara mengirim permintaan ke API.

1. Buat variabel lingkungan untuk nama layanan Endpoint Anda. Ini adalah nama yang Anda tentukan di kolom host pada dokumen OpenAPI. 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}/"

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

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

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

Melacak aktivitas API

1. Lihat grafik aktivitas untuk API Anda di halaman Endpoint > Layanan di Google Cloud Console.

   Melihat grafik aktivitas Endpoint

   Mungkin perlu waktu beberapa saat agar permintaan terlihat dalam grafik.

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

   Melihat log permintaan Endpoint

Membuat portal developer untuk API

Anda dapat menggunakan Portal Cloud Endpoints untuk membuat portal developer, yaitu situs yang dapat digunakan untuk berinteraksi dengan contoh API. Untuk mempelajari lebih lanjut, lihat Ringkasan Portal Cloud Endpoints.