Menyiapkan Cloud Endpoints OpenAPI untuk Cloud Functions dengan ESPv2
Halaman ini menunjukkan cara menyiapkan Cloud Endpoints di Cloud Functions. Endpoint menggunakan Extensible Service Proxy V2 (ESPv2) sebagai gateway API. Guna menyediakan pengelolaan API untuk Cloud Functions, Anda men-deploy container ESPv2 yang telah dibangun sebelumnya ke Cloud Run. Selanjutnya, amankan fungsi menggunakan IAM Cloud Functions sehingga ESPv2 dapat memanggilnya.
Dengan penyiapan ini, ESPv2 akan mencegat semua permintaan ke fungsi Anda dan melakukan pemeriksaan yang diperlukan (seperti autentikasi) sebelum memanggil fungsi tersebut. Saat fungsi tersebut merespons, ESPv2 akan mengumpulkan dan melaporkan telemetri, seperti yang ditunjukkan pada gambar di bawah. Anda dapat melihat metrik untuk fungsi Anda di halaman Endpoint > Layanan di Google Cloud Console.
Untuk ringkasan Cloud Endpoints, lihat Tentang Endpoint dan Arsitektur endpoint.
Bermigrasi ke ESPv2
Rilis Cloud Endpoints sebelumnya mendukung penggunaan Extensible Service Proxy (ESP) dengan Cloud Functions. Jika Anda sudah memiliki API yang ingin dimigrasikan ke ESPv2, lihat Bermigrasi ke Extensible Service Proxy V2 untuk mengetahui informasi selengkapnya.
{i>Task List <i}(Daftar Tugas)
Gunakan daftar tugas berikut saat Anda mengerjakan tutorial. Semua tugas diperlukan untuk menyelesaikan tutorial ini.
- Buat project Google Cloud, dan jika Anda belum men-deploy Cloud Functions sendiri, deploy fungsi backend contoh. Lihat Sebelum memulai.
- Cadangkan nama host Cloud Run untuk layanan ESPv2. Lihat Mereservasi nama host Cloud Run.
- Buat dokumen OpenAPI yang mendeskripsikan API Anda, dan konfigurasikan rute ke Cloud Functions Anda. Lihat Mengonfigurasi Endpoint.
- Men-deploy dokumen OpenAPI untuk membuat layanan terkelola. Lihat Men-deploy konfigurasi Endpoint.
- Build image Docker ESPv2 baru dengan konfigurasi layanan Endpoint Anda. Lihat Membuat image ESPv2 baru.
- Men-deploy container ESPv2 ke Cloud Run. Kemudian, beri ESPv2 izin Identity and Access Management (IAM) untuk memanggil layanan Anda. Lihat Men-deploy container ESPv2.
- Panggil fungsi. Lihat Mengirim permintaan ke API.
- Lacak aktivitas ke fungsi Anda. Lihat Aktivitas Tracking API.
- Hindari menimbulkan tagihan ke akun Google Cloud Anda. Lihat Pembersihan.
Biaya
Dalam dokumen ini, Anda menggunakan komponen Google Cloud yang dapat ditagih berikut:
Untuk membuat perkiraan biaya berdasarkan proyeksi penggunaan Anda,
gunakan kalkulator harga.
Setelah menyelesaikan tugas yang dijelaskan dalam dokumen ini, Anda dapat menghindari penagihan berkelanjutan dengan menghapus resource yang Anda buat. Untuk mengetahui informasi selengkapnya, lihat Pembersihan.
Sebelum memulai
Sebelum menggunakan Endpoint untuk Cloud Functions, sebaiknya Anda:
Buat project Google Cloud baru untuk digunakan saat Anda men-deploy container ESPv2 ke Cloud Run.
Buat project baru atau pilih project yang sudah ada untuk Cloud Functions Anda.
Untuk melakukan penyiapan:
Di konsol Google Cloud, buka halaman Manage resources dan buat project.
Pastikan penagihan diaktifkan untuk project Anda.
Catat ID project karena akan diperlukan nanti. Di bagian selanjutnya dari halaman ini, project ID ini disebut sebagai ESP_PROJECT_ID.
Catat nomor project karena akan diperlukan nanti. Di bagian selanjutnya dari halaman ini, nomor project ini disebut sebagai ESP_PROJECT_NUMBER.
Mendownload dan menginstal Google Cloud CLI.
Jika Anda belum men-deploy Cloud Functions backend, ikuti langkah-langkah di bagian Panduan Memulai: Menggunakan Google Cloud CLI untuk memilih atau membuat project Google Cloud dan men-deploy contoh fungsi. Catat region dan project ID tempat fungsi Anda di-deploy. Di bagian lain halaman ini, project ID ini disebut sebagai FUNCTIONS_PROJECT_ID.
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.
-
Pastikan gcloud CLI diberi otorisasi untuk mengakses data dan layanan Anda.
- Log in.
gcloud auth login
- 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.
- Log in.
-
Tetapkan wilayah.
gcloud config set run/region us-central1
-
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 dangateway-12345-uc.a.run.app
adalah CLOUD_RUN_HOSTNAME. - 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 fungsi Anda dan persyaratan autentikasi apa pun. Anda juga harus menambahkan kolom khusus Google yang berisi URL untuk setiap fungsi, sehingga ESPv2 memiliki informasi yang diperlukan untuk memanggil fungsi. Jika Anda baru menggunakan OpenAPI, lihat Ringkasan OpenAPI untuk mengetahui informasi selengkapnya
-
Buat file teks bernama
openapi-functions.yaml
. (Untuk memudahkan, halaman ini merujuk pada dokumen OpenAPI dengan nama file tersebut, tetapi Anda bisa memberinya nama lain jika mau.) -
Setiap fungsi Anda harus tercantum di bagian
paths
fileopenapi-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, kolomhost
harus berada pada level yang sama denganinfo
. -
Pada kolom
address
di bagianx-google-backend
, ganti REGION dengan region Google Cloud tempat fungsi Anda berada, FUNCTIONS_PROJECT_ID dengan project ID Google Cloud, dan FUNCTIONS_NAME dengan nama fungsi Anda. Contoh:x-google-backend: address: https://us-central1-myproject.cloudfunctions.net/helloGET
Jika Anda ingin mengamankan Cloud Function dengan hanya mengizinkan ESPv2 untuk memanggilnya, pastikan kolomaddress
menyertakan nama fungsi jikajwt_audience
tidak ditentukan. Contoh:x-google-backend: address: https://REGION-FUNCTIONS_PROJECT_ID.cloudfunctions.net/FUNCTIONS_NAME path_translation: CONSTANT_ADDRESS
Jikajwt_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 menghasilkan token ID saat memanggil Cloud Function untuk autentikasi. Token ID harus memilikiaudience
yang tepat yang menentukan host fungsi dan nama fungsi. ESPv2 menetapkanaudience
untuk token ID menggunakan nilai di kolomjwt_audience
jika ditentukan; jika tidak, ESPv2 akan menggunakan kolomaddress
. 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 + GCF description: Sample API on Cloud Endpoints with a Google Cloud Functions backend version: 1.0.0 host: gateway-12345-uc.a.run.app
Perhatikan nilai properti
title
dalam fileopenapi-functions.yaml
:title: Cloud Endpoints + GCF
Nilai properti
title
akan menjadi nama layanan Endpoint setelah Anda men-deploy konfigurasi.- 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:
- Pastikan Anda berada di direktori yang berisi dokumen OpenAPI Anda.
Mengupload konfigurasi dan membuat layanan terkelola.
gcloud endpoints services deploy openapi-functions.yaml \ --project ESP_PROJECT_ID
Tindakan ini akan membuat layanan Endpoint baru dengan nama yang Anda tentukan di kolom
host
pada fileopenapi-functions.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-functions.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
Setidaknya, Endpoint dan ESP mengharuskan layanan Google berikut diaktifkan:Nama | Judul |
---|---|
servicemanagement.googleapis.com |
Service Management API |
servicecontrol.googleapis.com |
Service Control API |
endpoints.googleapis.com |
Google Cloud Endpoints |
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.comgcloud 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 kolomname
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:
Download skrip ini ke mesin lokal tempat gcloud CLI diinstal.
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
-
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
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
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 Beta.Beri ESPv2 izin untuk memanggil Service Management dan Service Control.
- Di konsol Google Cloud, 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:
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, gunakan
helloGET
sebagai namanya. - 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 di 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
- 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, gunakan
gcloud projects add-iam-policy-binding PROJECT_NAME \ --member "serviceAccount:SERVICE_ACCOUNT" \ --role roles/servicemanagement.serviceControllerUntuk mengetahui informasi selengkapnya, lihat Apa yang dimaksud dengan peran dan izin?
Untuk mengetahui informasi selengkapnya, baca bagian Mengelola Akses melalui IAM.
Mengirim permintaan ke API
Bagian ini menunjukkan cara mengirim permintaan ke API.
- 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"
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 di 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 {i>backtick<i}. Saat Anda menempelkan contoh ke PowerShell, pastikan tidak ada spasi setelah tanda {i>backtick<i}. Untuk informasi tentang opsi yang digunakan dalam contoh permintaan, lihat Invoke-WebRequest dalam dokumentasi Microsoft.
Aplikasi pihak ketiga
Anda dapat menggunakan aplikasi pihak ketiga seperti permintaan Postman ekstensi browser Chrome.
- Pilih
GET
sebagai kata kerja HTTP. - Untuk header, pilih kunci
content-type
dan nilaiapplication/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 Endpoint.
Melacak aktivitas API
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.
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.
Pembersihan
Agar akun Google Cloud Anda tidak dikenakan biaya untuk resource yang digunakan pada halaman ini, ikuti langkah-langkah berikut.
Lihat Menghapus instance API dan API untuk mengetahui informasi tentang cara menghentikan layanan yang digunakan oleh tutorial ini.