Menyiapkan Endpoints OpenAPI untuk Cloud Run dengan ESPv2

Menyiapkan Endpoints OpenAPI untuk Cloud Run dengan ESPv2

OpenAPI   |  gRPC

Halaman ini menunjukkan cara menyiapkan Endpoints untuk Cloud Run. Endpoints menggunakan Extensible Service Proxy V2 (ESPv2) sebagai gateway API. Untuk menyediakan pengelolaan API bagi Cloud Run, Anda men-deploy container ESPv2 yang telah dibuat sebelumnya ke Cloud Run. Kemudian, Anda mengamankan layanan menggunakan Identity and Access Management (IAM) Cloud Run sehingga ESPv2 dapat memanggilnya.

Dengan penyiapan ini, ESPv2 mencegat semua permintaan ke layanan Anda dan melakukan pemeriksaan yang diperlukan (seperti autentikasi) sebelum memanggil layanan. Saat layanan merespons, ESPv2 mengumpulkan dan melaporkan telemetri, seperti yang ditunjukkan pada gambar berikut. Anda dapat melihat metrik untuk layanan di halaman Endpoints > Services di konsol Google Cloud .

Catatan: Dalam grafik contoh, ESPv2 dan "backend" di-deploy di dua instance Cloud Run terpisah.

Untuk ringkasan Cloud Endpoints, lihat Tentang Endpoints dan Arsitektur Endpoints.

Bermigrasi ke ESPv2

Rilis Endpoints sebelumnya mendukung penggunaan Extensible Service Proxy (ESP) dengan Cloud Run. Jika Anda memiliki API yang ada dan ingin memigrasikannya ke ESPv2, lihat Bermigrasi ke Extensible Service Proxy V2 untuk mengetahui informasi selengkapnya.

Daftar Tugas

Gunakan daftar tugas berikut saat Anda mengerjakan tutorial. Semua tugas diperlukan untuk menyelesaikan tutorial ini.

1. Buat Google Cloud project, dan jika Anda belum men-deploy Cloud Run Anda sendiri, deploy layanan backend contoh. Lihat Sebelum memulai.
2. Cadangkan nama host Cloud Run untuk layanan ESPv2. Lihat Mencadangkan nama host Cloud Run.
3. Buat dokumen OpenAPI yang mendeskripsikan API Anda, dan konfigurasi rute ke Cloud Run. Lihat Mengonfigurasi Endpoint.
4. Deploy dokumen OpenAPI untuk membuat layanan terkelola. Lihat Men-deploy konfigurasi Endpoints.
5. Buat image Docker ESPv2 baru dengan konfigurasi layanan Endpoints Anda. Lihat Membangun image ESPv2 baru.
6. Deploy container ESPv2 ke Cloud Run. Kemudian, berikan izin Identity and Access Management (IAM) kepada ESPv2 untuk memanggil layanan Anda. Lihat Men-deploy container ESPv2.
7. Panggil layanan. Lihat Mengirim permintaan ke API.
8. Melacak aktivitas ke layanan Anda. Lihat Melacak aktivitas API.
9. Hindari menimbulkan biaya pada akun Google Cloud Anda. Lihat Pembersihan.

Biaya

Di dokumen ini, Anda akan menggunakan komponen Google Cloudyang dapat ditagih berikut:

• Cloud Run
• Endpoints

Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda, gunakan kalkulator harga.

Pengguna Google Cloud baru mungkin memenuhi syarat untuk mendapatkan uji coba gratis.

Setelah menyelesaikan tugas yang dijelaskan dalam dokumen ini, Anda dapat menghindari penagihan berkelanjutan dengan menghapus resource yang Anda buat. Untuk mengetahui informasi selengkapnya, baca bagian Pembersihan.

Sebelum memulai

Untuk menyiapkan:

1. Di konsol Google Cloud , buka halaman Manage resources dan buat project.

   Buka halaman Kelola resource

2. Pastikan penagihan diaktifkan untuk project Anda.

   Pelajari cara mengaktifkan penagihan

3. Catat project ID karena akan diperlukan nanti. Di bagian selanjutnya dari halaman ini, project ID ini disebut sebagai ESPv2_PROJECT_ID.

4. Catat nomor project karena akan diperlukan nanti. Di bagian lain halaman ini, nomor project ini disebut sebagai ESPv2_PROJECT_NUMBER.

5. Download dan instal Google Cloud CLI.

   Download gcloud CLI

6. Jika Anda belum men-deploy layanan backend Cloud Run Anda sendiri, ikuti langkah-langkah di Panduan memulai: Men-deploy Container Contoh Bawaan untuk memilih atau membuat project Google Cloud dan men-deploy backend contoh. Catat region dan project ID tempat layanan Anda di-deploy. Di bagian selanjutnya dari halaman ini, project ID ini disebut sebagai BACKEND_PROJECT_ID. Nama layanan yang di-deploy disebut sebagai BACKEND_SERVICE_NAME.

Catatan: Untuk meningkatkan keamanan, konfigurasi layanan backend Cloud Run Anda agar hanya mengizinkan traffic ingress dari sumber internal. Hal ini mengarahkan semua permintaan eksternal melalui proxy ESPv2, mencegah akses internet langsung, serta memusatkan pengelolaan dan keamanan API. Lihat mengontrol traffic masuk ke layanan Cloud Run untuk mengetahui detail selengkapnya.

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.

Catatan: Setiap layanan Cloud Run ESPv2 hanya dapat dikaitkan dengan satu dokumen OpenAPI atau konfigurasi layanan gRPC. Cadangkan nama host Cloud Run baru untuk setiap dokumen.

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 ESPv2_CLOUD_RUN_SERVICE_NAME dengan nama yang ingin Anda gunakan untuk layanan.

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

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

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

   Misalnya, jika Anda menyetel ESPv2_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 ESPv2_CLOUD_RUN_HOSTNAME.

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

Mengonfigurasi Endpoint

Anda harus memiliki dokumen OpenAPI berdasarkan OpenAPI 2.0 atau OpenAPI 3.x yang mendeskripsikan platform aplikasi Anda dan persyaratan autentikasi apa pun. Untuk mempelajari lebih lanjut, lihat Versi OpenAPI yang didukung.

Anda juga perlu menambahkan kolom khusus Google yang berisi URL untuk setiap aplikasi agar 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-run.yaml. Untuk kenyamanan, halaman ini merujuk ke dokumen OpenAPI berdasarkan nama file tersebut, tetapi Anda dapat menamainya dengan nama lain jika mau.
2. Aplikasi backend App Engine Anda ditentukan dalam file openapi-run.yaml, baik dalam definisi x-google-backend (untuk OpenAPI 2.0) atau definisi x-google-api-management (untuk OpenAPI 3.x). Contoh:

   OpenAPI 2.0

   swagger: '2.0'
   info:
     title: Cloud Endpoints + Cloud Run
     description: Sample API on Cloud Endpoints with a Cloud Run backend
     version: 1.0.0
   host: ESPv2_CLOUD_RUN_HOSTNAME
   schemes:
     - https
   produces:
     - application/json
   x-google-backend:
     address: BACKEND_SERVICE_NAME
     protocol: h2
   paths:
     /hello:
       get:
         summary: Greet a user
         operationId: hello
         responses:
           '200':
             description: A successful response
             schema:
               type: string

   OpenAPI 3.x

   openapi: 3.0.4
   info:
     title: Cloud Endpoints + Cloud Run
     description: Sample API on Cloud Endpoints with a Cloud Run backend
     version: 1.0.0
   servers:
   - url: https://ESPv2_CLOUD_RUN_HOSTNAME
     x-google-endpoint: {}
   x-google-api-management:
     backends:
       cloudrun_backend:
         address: BACKEND_SERVICE_NAME
         protocol: h2
   x-google-backend: cloudrun_backend
   paths:
     /hello:
       get:
         summary: Greet a user
         operationId: hello
         responses:
           '200':
             description: A successful response
             content:
               application/json:
                 schema:
                   type: string

   Indentasi penting untuk format YAML. Misalnya, kolom host (untuk OpenAPI 2.0) atau objek servers harus berada di level yang sama dengan info.

3. Di kolom address, ganti BACKEND_SERVICE_NAME dengan URL sebenarnya dari layanan backend Cloud Run Anda, yang dibuat pada Langkah 6 di Sebelum Anda Memulai.

   Contoh ini mengasumsikan bahwa Anda menggunakan layanan backend hello yang dibuat di Panduan memulai: Men-deploy Container Contoh Bawaan. Jika Anda menggunakan layanan Cloud Run backend yang berbeda, ganti BACKEND_SERVICE_NAME dengan URL layanan Cloud Run Anda.

4. Tentukan nama host untuk layanan Anda. Nilai yang diperlukan bergantung pada versi spesifikasi OpenAPI yang Anda gunakan.

   OpenAPI 2.0

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

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

   OpenAPI 3.x

   Di kolom url objek servers, tentukan URL lengkap, termasuk ID protokol https:// dan ESPv2_CLOUD_RUN_HOSTNAME, bagian nama host dari URL yang dicadangkan di Mencadangkan nama host Cloud Run. Contoh:

   openapi: 3.0.4
   info:
     title: Cloud Endpoints + Cloud Run
     description: Sample API on Cloud Endpoints with a Cloud Run backend
     version: 1.0.0
   servers:
   - url: https://gateway-12345-uc.a.run.app
     x-google-endpoint: {}

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

   title: Cloud Endpoints + Cloud Run

   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.

Mengonfigurasi Endpoints agar memerlukan kunci API

Untuk mengontrol akses ke API, Anda dapat mengonfigurasi Endpoints agar memerlukan kunci API. Klien yang memanggil API Anda harus memberikan kunci API yang terkait dengan project Anda. Lihat Membatasi akses API dengan kunci API untuk mengetahui informasi selengkapnya.

Jika belum memiliki kunci API yang terkait dengan Google Cloud project yang Anda gunakan dalam panduan memulai ini, Anda dapat menambahkannya dengan mengikuti langkah-langkah di Membuat Kunci API.

Untuk menguji penerapan kunci API menggunakan kunci API yang terkait dengan Google Cloud project Anda, ikuti langkah-langkah berikut:

1. Aktifkan dukungan kunci API untuk layanan Anda. Masukkan perintah berikut, dengan:
   • ESPv2_CLOUD_RUN_HOSTNAME adalah komponen nama host dari URL yang ditetapkan untuk layanan ESPv2 di Cloud Run. Objek ini digunakan dalam kolom host dokumen OpenAPI untuk menentukan lokasi tempat API dihosting.

   gcloud services enable ESPv2_CLOUD_RUN_HOSTNAME

2. Buka file openapi-run.yaml project Anda.
3. Tambahkan skema keamanan api_key di bagian securityDefinitions. Ini menentukan skema keamanan yang disebut api_key yang mencari kunci API di header x-api-key.

   swagger: '2.0'
   host: ESPv2_CLOUD_RUN_HOSTNAME
   info:
     version: 1.0.0
     title: Cloud Endpoints + Cloud Run
   schemes:
     - https
   produces:
     - application/json
   securityDefinitions:
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"
       

4. Terapkan skema keamanan api_key ke semua metode API dengan menambahkan direktif security: - api_key: [] di tingkat teratas file openapi-run.yaml.

   swagger: '2.0'
   host: ESPv2_CLOUD_RUN_HOSTNAME
   info:
     version: 1.0.0
     title: Cloud Endpoints + Cloud Run
   schemes:
     - https
   produces:
     - application/json
   securityDefinitions:
     api_key:
       type: "apiKey"
       name: "key"
       in: "query"
   security:
     - api_key: []
       

5. Jika Anda ingin melindungi metode tertentu, bukan seluruh API, tambahkan perintah security: [] kosong di tingkat teratas, lalu tambahkan perintah security: - api_key: [] ke definisi metode tertentu yang ingin Anda lindungi.

     paths:
       /shelves:
         get:
           summary: Lists all shelves
           operationId: listShelves
           security: []
         post:
           summary: Creates a new shelf
           operationId: createShelf
           security:
           - api_key: []
       

6. Setelah memodifikasi file openapi-run.yaml, deploy konfigurasi yang telah diupdate ke layanan Endpoints Anda.

Memanggil API menggunakan kunci API

Jika API atau metode API memerlukan kunci API, berikan kunci menggunakan parameter kueri bernama key, seperti yang ditunjukkan dalam contoh curl berikut:

 curl "${ESPv2_CLOUD_RUN_HOSTNAME}/echo?key=${API_KEY}"

Praktik terbaik

Jika Anda mengandalkan kunci API untuk melindungi akses ke API dan data pengguna, pastikan Anda menyetel tanda --service_control_network_fail_policy ke close saat mengonfigurasi opsi startup Extensible Service Proxy V2 (ESPv2). Nilai default untuk tanda adalah open.

ESPv2 memanggil Service Control untuk memverifikasi kunci API. Jika terjadi kegagalan jaringan saat terhubung ke Service Control dan ESPv2 tidak dapat memverifikasi kunci API, semua potensi permintaan yang dibuat ke API Anda dengan kunci palsu akan ditolak.

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-run.yaml \
     --project ESPv2_PROJECT_ID

   Tindakan ini akan membuat layanan Endpoints baru dengan nama yang Anda tentukan di kolom host pada file openapi-run.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 [ESPv2_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-run.yaml lagi pada hari yang sama, nomor revisi akan bertambah di 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 Endpoint.

Memeriksa layanan yang diperlukan

Minimal, Endpoints dan ESP memerlukan layanan Google berikut diaktifkan:

Nama	Judul
servicemanagement.googleapis.com	Service Management API
servicecontrol.googleapis.com	Service Control API

Dalam sebagian besar kasus, perintah gcloud endpoints services deploy mengaktifkan layanan yang diperlukan 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 men-deploy konfigurasi Endpoints ke projectGoogle Cloud yang sudah ada dan layanan ini dinonaktifkan secara eksplisit di project tersebut.

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.

Catatan:

Langkah ini wajib dilakukan.

Konfigurasi layanan harus dibangun ke dalam image Docker baru karena Cloud Run adalah layanan menskalakan ke nol. Artinya, jika tidak ada traffic, semua instance akan dihapus. Saat traffic meningkat, instance baru dibuat sesuai permintaan. Pembuatan instance layanan jenis ini juga disebut cold start. Lihat dokumentasi Konkurensi Cloud Run untuk mengetahui informasi selengkapnya.

Jika image Docker tidak memiliki konfigurasi layanan yang di-build di dalamnya, Cloud Run harus melakukan dua panggilan API ke Google ServiceManagement saat cold start. Panggilan ini dihitung dalam kuota Google ServiceManagement API Anda.

Dengan mem-build konfigurasi layanan ke dalam image Docker ESPv2, Anda menghapus dua panggilan API dan menghindari dampak pada jumlah kuota untuk layanan Google ServiceManagement. Langkah ini juga mempercepat pembuatan instance layanan baru dan mengurangi latensi untuk permintaan yang menunggu instance baru.

Anda harus menjalankan kembali seluruh langkah ini dan men-deploy ulang container baru:

• Setiap kali Anda mengubah dan men-deploy ulang konfigurasi layanan Endpoints. Jika tidak, perubahan pada konfigurasi layanan tidak akan diteruskan ke ESPv2.
• Saat versi baru ESPv2 dirilis. Jika tidak, ESPv2 versi lama akan tetap di-deploy.

Untuk membuat konfigurasi layanan menjadi image Docker ESPv2 baru:

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

   Catatan:

   Skrip ini memerlukan bash. Jika tidak menggunakan macOS/Linux, Anda dapat menjalankannya di Cloud Shell, Compute Engine, atau Windows Subsystem for Linux.

2. Jalankan skrip dengan perintah berikut:

   chmod +x gcloud_build_image
   
   ./gcloud_build_image -s ESPv2_CLOUD_RUN_HOSTNAME \
       -c CONFIG_ID -p ESPv2_PROJECT_ID

   Catatan:

   Skrip ini dirancang untuk membuat folder dalam direktori /tmp. Pastikan Anda memiliki akses tulis untuk direktori /tmp saat menjalankan skrip ini.

   Jika akses tulis tidak tersedia untuk direktori /tmp, Anda harus mengubah skrip untuk menentukan direktori alternatif tempat Anda memiliki akses yang diperlukan untuk membuat folder.

   Untuk ESPv2_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, membuat konfigurasi layanan menjadi image ESPv2 baru, dan mengupload image baru ke registry container project Anda. Skrip otomatis menggunakan rilis ESPv2 terbaru, yang ditunjukkan oleh ESPv2_VERSION dalam nama gambar output. Gambar output diupload ke:

   gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_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"

   Catatan:

   Teruskan tanda -z ke skrip untuk membuat gambar di lokasi registry yang berbeda.

   Misalnya, untuk mengirimkan image ESPv2 yang dihasilkan ke pusat data Uni Eropa, teruskan -z eu ke skrip.

Men-deploy container ESPv2

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

   gcloud run deploy ESPv2_CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --allow-unauthenticated \
     --platform managed \
     --project=ESPv2_PROJECT_ID

   Catatan: Jika Anda ingin ESPv2 mengelola akses, gunakan flag --allow-unauthenticated untuk memastikan ESPv2 memverifikasi token JWT. Jika tanda tidak digunakan, token JWT akan dicegat dan diverifikasi oleh server IAM kontrol akses Cloud Run. Karena IAM dan ESPv2 menggunakan header Otorisasi yang sama, keduanya tidak dapat bekerja sama. Pastikan hanya menggunakan salah satunya. Sebaiknya gunakan IAM, bukan ESPv2 untuk mengelola akses.

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 ESPv2_CLOUD_RUN_SERVICE_NAME \
     --image="gcr.io/ESPv2_PROJECT_ID/endpoints-runtime-serverless:ESPv2_VERSION-ESPv2_CLOUD_RUN_HOSTNAME-CONFIG_ID" \
     --set-env-vars=ESPv2_ARGS=--cors_preset=basic \
     --allow-unauthenticated \
     --platform managed \
     --project ESPv2_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 Extensible Service Proxy V2.

3. Memberikan izin ESPv2 untuk memanggil Service Management dan Service Control.
Catatan: Langkah ini tidak diperlukan jika instance Cloud Run ESPv2 di-deploy tanpa menggunakan flag --service-account
• 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_ID \
       --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 layanan Cloud Run Anda. Jalankan perintah berikut untuk setiap layanan. Dalam perintah berikut:
   Catatan:

   Langkah ini tidak diperlukan jika layanan ESPv2 Cloud Run di-deploy tanpa menggunakan tanda --service-account dan layanan backend BACKEND_SERVICE_NAME di-deploy di project ESPv2_PROJECT_NUMBER.

   • Ganti BACKEND_SERVICE_NAME dengan nama layanan Cloud Run yang dipanggil. Jika Anda menggunakan layanan backend yang dibuat di Panduan memulai: Men-deploy Container Contoh Bawaan, gunakan hello sebagai nilai ini.
   • Ganti ESPv2_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 run services add-iam-policy-binding BACKEND_SERVICE_NAME \
     --member "serviceAccount:[e-mail]" \
     --role "roles/run.invoker" \
     --platform managed \
     --project BACKEND_PROJECT_ID

Untuk mengetahui informasi selengkapnya, lihat Mengelola akses menggunakan 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"

Linux atau Mac OS

Gunakan curl untuk mengirim permintaan HTTP menggunakan variabel lingkungan ENDPOINTS_HOST yang Anda tetapkan di langkah sebelumnya.

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

PowerShell

Gunakan Invoke-WebRequest untuk mengirim permintaan HTTP menggunakan variabel lingkungan ENDPOINTS_HOST yang Anda tetapkan pada langkah sebelumnya.

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

Pada contoh sebelumnya, dua baris pertama diakhiri dengan tanda petik terbalik. Saat menempelkan contoh ke PowerShell, pastikan tidak ada spasi setelah tanda petik terbalik. Untuk mengetahui informasi tentang opsi yang digunakan dalam contoh permintaan, lihat Invoke-WebRequest dalam dokumentasi Microsoft.

Aplikasi pihak ketiga

Anda dapat menggunakan aplikasi pihak ketiga seperti ekstensi browser Chrome Postman untuk membuat permintaan.

• Pilih GET sebagai kata kerja HTTP.
• Untuk header, pilih kunci content-type dan nilai application/json.

• Gunakan URL sebenarnya, bukan variabel lingkungan, misalnya:

  https://gateway-12345-uc.a.run.app/hello
  

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

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

Catatan: Jika Anda ingin memberi tahu kami apa yang Anda sukai tentang tutorial ini, silakan berikan masukan di bagian bawah halaman ini. Masukan Anda membantu kami meningkatkan kualitas tutorial ini.
Jika Anda mendapatkan error, bergabunglah ke grup Google google-cloud-endpoints dan beri tahu kami apa yang salah. Grup ini menerima respons dari pengguna Endpoints lainnya dan dari engineer Google, yang memantau grup.

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

Pembersihan

Agar akun Google Cloud Anda tidak dikenai biaya untuk resource yang digunakan pada halaman ini, ikuti langkah-langkah berikut.

Lihat Menghapus API dan instance API untuk mengetahui informasi tentang cara menghentikan layanan yang digunakan oleh tutorial ini.

Langkah berikutnya

• Pelajari Cloud Run lebih lanjut
• Pelajari lebih lanjut cara men-deploy konfigurasi Endpoints
• Membagikan API Anda kepada developer lain
• Mempelajari autentikasi
• Pelajari opsi dukungan komunitas