Ekstensi OpenAPI

OpenAPI   |  gRPC

Cloud Endpoints menerima kumpulan ekstensi khusus Google untuk spesifikasi OpenAPI yang mengonfigurasi perilaku Extensible Service Proxy (ESP) dan Service Control. Halaman ini menjelaskan ekstensi khusus Google untuk spesifikasi OpenAPI.

Meskipun contoh yang diberikan di bawah ini dalam format YAML, JSON juga didukung.

Konvensi penamaan

Ekstensi Google OpenAPI memiliki nama yang diawali dengan awalan x-google-.

x-google-allow

x-google-allow: [configured | all]

Ekstensi ini digunakan di tingkat teratas spesifikasi OpenAPI untuk menunjukkan jalur URL yang harus diizinkan melalui ESP.

Nilai yang mungkin adalah configured dan all.

Nilai defaultnya adalah configured, yang berarti hanya metode API yang telah Anda cantumkan dalam spesifikasi OpenAPI yang akan disalurkan melalui ESP.

Saat all digunakan, panggilan yang tidak dikonfigurasi—dengan atau tanpa kunci API atau autentikasi pengguna—akan meneruskan ESP ke API Anda.

Catatan: Jika properti basePath juga dikonfigurasi dalam konfigurasi layanan, header ini hanya berlaku untuk jalur URL yang diawali dengan nilai properti basePath. URL yang bukan bagian dari basePath tidak akan diteruskan, terlepas dari properti x-google-allow.

ESP memproses panggilan ke API Anda dengan cara yang peka huruf besar/kecil. Misalnya, ESP menganggap /widgets dan /Widgets sebagai metode API yang berbeda.

Saat all digunakan, Anda harus memberikan perhatian ekstra di dua area:

• Kunci API atau aturan autentikasi apa pun.
• Pemilihan rute jalur backend di layanan Anda.

Sebagai praktik terbaik, sebaiknya konfigurasi API Anda untuk menggunakan pemilihan rute jalur yang peka huruf besar/kecil. Dengan menggunakan perutean yang peka huruf besar/kecil, API Anda akan menampilkan kode status HTTP 404 jika metode yang diminta dalam URL tidak cocok dengan nama metode API yang tercantum dalam spesifikasi OpenAPI Anda. Perhatikan bahwa framework aplikasi web seperti Node.js Express memiliki setelan untuk mengaktifkan atau menonaktifkan perutean yang peka huruf besar/kecil. Perilaku default tergantung pada framework yang Anda gunakan. Sebaiknya tinjau setelan dalam framework untuk memastikan pemilihan rute yang peka huruf besar/kecil telah diaktifkan. Rekomendasi ini sesuai dengan Spesifikasi OpenAPI v2.0 yang menyatakan: "Semua nama kolom dalam spesifikasi peka huruf besar/kecil."

Contoh

Asumsikan bahwa:

• x-google-allow disetel ke all.
• Metode API widgets tercantum dalam spesifikasi OpenAPI Anda, tetapi tidak tercantum dalam Widgets.
• Anda telah mengonfigurasi spesifikasi OpenAPI agar mewajibkan kunci API.

Karena widgets tercantum dalam spesifikasi OpenAPI Anda, ESP akan memblokir permintaan berikut karena tidak memiliki kunci API:

https://my-project-id.appspot.com/widgets

Karena Widgets tidak tercantum dalam spesifikasi OpenAPI, ESP meneruskan permintaan berikut ke layanan Anda tanpa kunci API:

https://my-project-id.appspot.com/Widgets/

Jika API menggunakan perutean yang peka huruf besar/kecil (dan Anda belum mengarahkan panggilan ke "Widget" ke kode apa pun), backend API akan menampilkan 404. Namun, jika Anda menggunakan perutean yang tidak peka huruf besar/kecil, backend API akan mengarahkan panggilan ini ke "widget".

Bahasa dan framework yang berbeda memiliki metode yang berbeda untuk mengontrol sensitivitas huruf besar dan perutean. Baca dokumentasi untuk framework Anda guna mengetahui detailnya.

x-google-backend

Ekstensi x-google-backend menentukan cara merutekan permintaan ke backend lokal atau jarak jauh. Ekstensi dapat ditentukan di tingkat teratas dan/atau tingkat operasi spesifikasi OpenAPI.

Secara default, ESP dikonfigurasi untuk mem-proxy semua traffic ke satu backend lokal. Alamat backend lokal ditentukan oleh flag --backend (default-nya adalah http://127.0.0.1:8081). Anda dapat menggunakan ekstensi x-google-backend untuk mengganti perilaku default ini dan menentukan satu atau beberapa backend lokal atau jarak jauh yang dapat menerima permintaan.

Ekstensi x-google-backend juga dapat mengonfigurasi setelan lain untuk backend lokal dan jarak jauh, seperti autentikasi dan waktu tunggu. Semua konfigurasi ini dapat diterapkan per operasi.

Catatan: ESP dan ESPv2 mendukung ekstensi ini, tetapi ESPv2 mendukung lebih banyak opsi konfigurasi. Semua konfigurasi x-google-backend yang berfungsi dengan ESP dijamin berfungsi dengan ESPv2. Harap migrasikan ke ESPv2 untuk menggunakan fitur baru. Fitur yang tidak didukung oleh ESP didokumentasikan per kolom di bawah.

Ekstensi x-google-backend berisi kolom berikut:

address

address: URL

Opsional. URL backend target. Skema alamat harus http atau https.

Saat merutekan ke backend jarak jauh (Serverless), alamat harus ditetapkan dan bagian skema harus https.

Jika operasi menggunakan x-google-backend tetapi tidak menentukan address, ESPv2 akan merutekan permintaan ke backend lokal yang ditentukan oleh flag --backend.

Catatan: Untuk ESPv2, x-google-backend dapat digunakan dengan backend lokal dengan menghapus alamat. Untuk ESP, kolom ini wajib diisi. x-google-backend hanya dapat digunakan untuk backend jarak jauh.

jwt_audience | disable_auth

Hanya satu dari dua properti ini yang harus ditetapkan.

Jika operasi menggunakan x-google-backend tetapi tidak menentukan jwt_audience atau disable_auth, ESPv2 akan otomatis menetapkan jwt_audience ke default agar cocok dengan address. Jika address tidak disetel, ESPv2 akan otomatis menyetel disable_auth ke true.

jwt_audience

jwt_audience: string

Opsional. Audiens JWT ditentukan saat ESPv2 memperoleh token ID instance, yang kemudian digunakan saat membuat permintaan backend target.

Catatan: Penggunaan jwt_audience dengan ekstensi x-google-backend hanya didukung saat ESPv2 di-deploy di Google Cloud.

Saat mengonfigurasi Endpoint untuk Serverless, backend jarak jauh harus diamankan agar hanya mengizinkan traffic dari ESPv2. ESPv2 akan melampirkan token ID instance ke header Authorization saat mem-proxy permintaan. Token ID instance merepresentasikan akun layanan runtime yang digunakan untuk men-deploy ESPv2. Backend jarak jauh kemudian dapat memverifikasi bahwa permintaan tersebut berasal dari ESPv2 berdasarkan token yang terpasang ini.

Misalnya, backend jarak jauh yang di-deploy di Cloud Run dapat menggunakan IAM untuk:

1. Batasi pemanggilan yang tidak diautentikasi dengan mencabut roles/run.invoker dari utama allUsers khusus.
2. Hanya izinkan ESPv2 untuk memanggil backend dengan memberikan peran roles/run.invoker ke akun layanan runtime ESPv2.

Secara default, ESPv2 akan membuat token ID instance dengan audiens JWT yang cocok dengan kolom address. Menentukan jwt_audience secara manual hanya diperlukan jika backend target menggunakan autentikasi berbasis JWT dan audiens yang diharapkan berbeda dari nilai yang ditentukan di kolom address. Untuk backend jarak jauh yang di-deploy di App Engine atau dengan IAP, Anda harus mengganti audiens JWT. App Engine dan IAP menggunakan client ID OAuth sebagai audiens yang diharapkan.

Saat fitur ini diaktifkan, ESPv2 akan mengubah header dalam permintaan. Jika permintaan memiliki header Authorization yang sudah disetel, ESPv2 akan:

1. Salin nilai asli ke header baru X-Forwarded-Authorization.
2. Ganti header Authorization dengan token ID instance.

Oleh karena itu, jika klien API menetapkan header Authorization, backend yang berjalan di belakang ESPv2 harus menggunakan header X-Forwarded-Authorization untuk mengambil seluruh JWT. Backend harus memverifikasi JWT di header ini, karena ESPv2 tidak akan melakukan verifikasi jika metode autentikasi tidak dikonfigurasi.

Catatan: Jika ESPv2 dikonfigurasi dengan autentikasi, sebaiknya gunakan header X-Endpoint-API-UserInfo untuk mengambil payload JWT terverifikasi. Lihat Menerima hasil yang diautentikasi di API Anda untuk detail selengkapnya.

disable_auth

disable_auth: bool

Opsional. Properti ini menentukan apakah ESPv2 harus mencegah perolehan token ID instance dan mencegah pelampirannya pada permintaan.

Saat mengonfigurasi backend target, Anda mungkin tidak ingin menggunakan IAP atau IAM untuk mengautentikasi permintaan dari ESPv2 jika salah satu kondisi berikut terpenuhi:

1. Backend harus mengizinkan pemanggilan yang tidak diautentikasi.
2. Backend memerlukan header Authorization asli dari klien API dan tidak dapat menggunakan X-Forwarded-Authorization (dijelaskan di bagian jwt_audience).

Dalam hal ini, tetapkan kolom ini ke true.

path_translation

path_translation: [ APPEND_PATH_TO_ADDRESS | CONSTANT_ADDRESS ]

Opsional. Menetapkan strategi terjemahan jalur yang digunakan oleh ESPv2 saat membuat proxy permintaan ke backend target.

Untuk detail selengkapnya tentang terjemahan jalur, lihat bagian Memahami terjemahan jalur.

Jika x-google-backend digunakan di level teratas spesifikasi OpenAPI, path_translation ditetapkan secara default ke APPEND_PATH_TO_ADDRESS, dan saat x-google-backend digunakan pada level operasi spesifikasi OpenAPI, path_translation ditetapkan secara default ke CONSTANT_ADDRESS. Jika kolom address tidak ada, path_translation akan tetap tidak ditentukan dan tidak akan terjadi.

deadline

deadline: double

Opsional. Jumlah detik untuk menunggu respons lengkap dari permintaan. Respons yang memerlukan waktu lebih lama dari batas waktu yang dikonfigurasi akan habis. Batas waktu default adalah 15.0 detik.

Nilai non-positif tidak akan diberlakukan. Dalam kasus ini, ESPv2 akan otomatis menggunakan nilai default.

Batas waktu tidak dapat dinonaktifkan, tetapi dapat ditetapkan ke jumlah yang tinggi — misalnya, 3600.0 selama satu jam.

Peringatan: Batas waktu yang lama dapat menyebabkan proxy kelebihan beban dengan terlalu banyak koneksi TCP jika respons backend lambat. Tenggat waktu yang singkat dapat menyebabkan beberapa permintaan yang lebih mahal gagal secara konsisten. Seimbangkan batasan ini untuk memilih batas waktu yang tepat.

Catatan: Properti deadline adalah fitur baru di ESPv2. Fitur ini tidak didukung oleh ESP.

protocol

protocol: [ http/1.1 | h2 ]

Opsional. Protokol yang digunakan untuk mengirim permintaan ke backend. Nilai yang didukung adalah http/1.1 dan h2.

Nilai defaultnya adalah http/1.1 untuk backend HTTP dan HTTPS.

Untuk backend HTTP aman (https://) yang mendukung HTTP/2, tetapkan kolom ini ke h2 untuk meningkatkan performa. Opsi ini direkomendasikan untuk backend serverless Google Cloud.

Catatan: Ini adalah fitur baru di ESPv2. Fitur ini tidak didukung oleh ESP.

Mengaktifkan dukungan backend di ESP

ESPv2 akan otomatis mendeteksi saat x-google-backend dikonfigurasi.

ESP memerlukan perubahan konfigurasi manual untuk mengaktifkan fitur ini. Aktifkan dukungan x-google-backend di ESP dengan memberikan argumen --enable_backend_routing saat menjalankan penampung ESP. (Untuk runtime yang tidak mengontrol opsi penampung ESP, opsi ini sudah disediakan untuk Anda.) Berikut adalah contoh pengaktifan dukungan x-google-backend saat men-deploy penampung ESP ke GKE (contoh ini dibuat berdasarkan contoh Endpoint di Tutorial GKE):

- name: esp
  image: gcr.io/endpoints-release/endpoints-runtime:1
  args: [
    "--http_port", "8081",
    "--service", "SERVICE_NAME",
    "--rollout_strategy", "managed",
    "--enable_backend_routing"
  ]

Memahami terjemahan jalur

Karena ESP menangani permintaan, ESP akan mengambil jalur permintaan asli dan menerjemahkannya sebelum membuat permintaan ke backend target. Persisnya, cara penerjemahan ini bergantung pada strategi penerjemahan jalur mana yang Anda gunakan. Ada dua strategi penerjemahan jalur:

• APPEND_PATH_TO_ADDRESS: Jalur permintaan backend target dihitung dengan menambahkan jalur permintaan asli ke URL address ekstensi x-google-backend.
• CONSTANT_ADDRESS: Jalur permintaan target bersifat konstan, seperti yang ditentukan oleh URL address dari ekstensi x-google-backend. Jika jalur OpenAPI yang terkait berisi parameter, nama parameter dan nilainya menjadi parameter kueri.

Contoh:

• APPEND_PATH_TO_ADDRESS
  • address: https://my-project-id.appspot.com/BASE_PATH
  • Dengan parameter jalur OpenAPI
    • Jalur OpenAPI: /hello/{name}
    • Jalur permintaan: /hello/world
    • URL permintaan target: https://my-project-id.appspot.com/BASE_PATH/hello/world
  • Tanpa parameter jalur OpenAPI
    • Jalur OpenAPI: /hello
    • Jalur permintaan: /hello
    • URL permintaan target: https://my-project-id.appspot.com/BASE_PATH/hello
• CONSTANT_ADDRESS
  • address: https://us-central1-my-project-id.cloudfunctions.net/helloGET
  • Dengan parameter jalur OpenAPI
    • Jalur OpenAPI: /hello/{name}
    • Jalur permintaan: /hello/world
    • URL permintaan target: https://us-central1-my-project-id.cloudfunctions.net/helloGET?name=world
  • Tanpa parameter jalur OpenAPI
    • Jalur OpenAPI: /hello
    • Jalur permintaan: /hello
    • URL permintaan target: https://us-central1-my-project-id.cloudfunctions.net/helloGET

x-google-endpoints

Bagian ini menjelaskan penggunaan ekstensi x-google-endpoints.

Mengonfigurasi DNS di domain cloud.goog

Jika telah men-deploy aplikasi ke Compute Engine atau Google Kubernetes Engine, Anda dapat membuat entri DNS untuk layanan Endpoint di domain cloud.goog dengan menambahkan kode berikut ke dokumen OpenAPI:

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  target: "IP_ADDRESS"

Tambahkan ekstensi x-google-endpoints di bagian atas dokumen OpenAPI Anda (tidak diindentasi atau bertingkat). Anda harus mengonfigurasi nama domain dalam format: .endpoints.PROJECT_ID.cloud.goog

Contoh:

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  target: "192.0.2.1"

Domain .cloud.goog dikelola oleh Google dan dibagikan oleh pelanggan Google Cloud. Karena project ID Google Cloud bersifat unik secara global, nama domain dalam format .endpoints.PROJECT_ID.cloud.goog adalah nama domain yang unik untuk API Anda.

Agar lebih mudah, konfigurasikan kolom host dan kolom x-google-endpoints.name agar sama. Saat Anda men-deploy dokumen OpenAPI, Pengelolaan Layanan akan membuat:

• Layanan terkelola dengan nama yang Anda tentukan di kolom host.
• Data A DNS menggunakan nama dan alamat IP yang Anda konfigurasi di ekstensi x-google-endpoints.

Untuk API yang dihosting di lingkungan fleksibel App Engine, Anda dapat menggunakan domain appspot.com. Untuk informasi selengkapnya, lihat Mengonfigurasi Endpoint.

Mengonfigurasi ESP untuk mengizinkan permintaan CORS

Jika API Anda dipanggil dari aplikasi web pada origin yang berbeda, API Anda harus mendukung Cross-Origin Resource Sharing (CORS). Lihat Menambahkan dukungan CORS ke ESP untuk mengetahui informasi tentang cara mengonfigurasi ESP guna mendukung CORS.

Jika perlu mengimplementasikan dukungan CORS kustom dalam kode backend, tetapkan allowCors: True sehingga ESP meneruskan semua permintaan CORS ke kode backend Anda:

x-google-endpoints:
- name: "API_NAME.endpoints.PROJECT_ID.cloud.goog"
  allowCors: True

Tambahkan ekstensi x-google-endpoints di tingkat atas dokumen OpenAPI Anda (tidak diindentasi atau bertingkat), misalnya:

swagger: "2.0"
host: "my-cool-api.endpoints.my-project-id.cloud.goog"
x-google-endpoints:
- name: "my-cool-api.endpoints.my-project-id.cloud.goog"
  allowCors: True

x-google-issuer

x-google-issuer: URI | EMAIL_ADDRESS

Ekstensi ini digunakan di bagian securityDefinitions OpenAPI untuk menentukan penerbit kredensial. Nilainya dapat berupa nama host atau alamat email.

x-google-jwks_uri

x-google-jwks_uri: URI

URI kunci publik penyedia yang disetel untuk memvalidasi tanda tangan Token Web JSON.

ESP mendukung dua format kunci publik asimetris yang ditentukan oleh ekstensi OpenAPI x-google-jwks_uri:

• Format kumpulan JWK. Contoh:

  x-google-jwks_uri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  

• X509. Contoh:

  x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/[e-mail]"
  

Jika Anda menggunakan format kunci simetris, tetapkan x-google-jwks_uri ke URI file yang berisi string kunci yang dienkode base64url.

Jika Anda menghapus x-google-jwks_uri, ESP akan mengikuti protokol OpenID Connect Discovery untuk otomatis menemukan URI JWKS untuk penyedia OpenID tertentu. ESP akan membuat permintaan ke x-google-issuer/.well-known/openid-configuration, mengurai respons JSON, dan membaca URI JWKS dari kolom jwks_uri tingkat atas.

Perlu diketahui bahwa menghapus x-google-jwks_uri akan mengakibatkan waktu cold start yang lebih tinggi, karena ESP harus membuat panggilan jarak jauh tambahan saat startup. Oleh karena itu, sebaiknya hapus kolom ini jika URI JWKS sering berubah. Sebagian besar penyedia OpenID tersertifikasi (seperti Google, Auth0, dan Okta) memiliki URI JWKS yang stabil.

x-google-jwt-locations

Secara default, JWT diteruskan di header Authorization (diawali dengan "Bearer "), header X-Goog-Iap-Jwt-Assertion, atau di parameter kueri access_token. Lihat Melakukan panggilan yang diautentikasi ke Endpoints API untuk mengetahui contoh cara meneruskan JWT.

Atau, gunakan ekstensi x-google-jwt-locations di bagian SecurityDefinitions OpenAPI untuk memberikan lokasi yang disesuaikan dari tempat mengekstrak token JWT.

Catatan: Jika Anda menentukan ekstensi x-google-jwt-locations, Endpoint akan mengabaikan semua lokasi default.

Ekstensi x-google-jwt-locations menerima daftar lokasi JWT. Setiap lokasi JWT berisi kolom berikut:

Elemen	Deskripsi
header/query	Wajib. Nama untuk header yang berisi JWT, atau nama untuk parameter kueri yang berisi JWT.
value_prefix	Opsional. Hanya untuk header. Jika value_prefix ditetapkan, nilainya harus cocok dengan awalan nilai header yang berisi JWT.

Contoh:

x-google-jwt-locations:
  # Expect header "Authorization": "MyBearerToken <TOKEN>"
  - header: "Authorization"
    value_prefix: "MyBearerToken "
  # expect header "jwt-header-foo": "jwt-prefix-foo<TOKEN>"
  - header: "jwt-header-foo"
    value_prefix: "jwt-prefix-foo"
  # expect header "jwt-header-bar": "<TOKEN>"
  - header: "jwt-header-bar"
  # expect query parameter "jwt_query_bar=<TOKEN>"
  - query: "jwt_query_bar"

Jika Anda hanya ingin mendukung subset lokasi JWT default, cantumkan secara eksplisit di ekstensi x-google-jwt-locations. Misalnya, untuk menyertakan dukungan hanya untuk header Authorization dengan awalan "Bearer ":

  x-google-jwt-locations:
    # Support the default header "Authorization": "Bearer <TOKEN>"
    - header: "Authorization"
      value_prefix: "Bearer "

Catatan: Saat ini, fitur ini tidak didukung oleh ESP. Harap lakukan migrasi ke ESPv2 untuk menggunakan fitur ini.

x-google-audiences

x-google-audiences: STRING

Ekstensi ini digunakan di bagian securityDefinitions OpenAPI untuk memberikan daftar audiens yang harus cocok dengan kolom aud JWT selama autentikasi JWT. Ekstensi ini menerima satu string dengan nilai yang dipisahkan oleh koma. Spasi tidak diizinkan di antara audiens. Jika tidak ditentukan, kolom aud JWT harus cocok dengan kolom host dalam dokumen OpenAPI, kecuali jika flag --disable_jwt_audience_service_name_check digunakan. Jika tanda ini digunakan dan x-google-audiences tidak ditentukan, kolom aud JWT tidak akan dicentang.

securityDefinitions:
  google_id_token:
    type: oauth2
    authorizationUrl: ""
    flow: implicit
    x-google-issuer: "https://accounts.google.com"
    x-google-jwks_uri: "https://www.googleapis.com/oauth2/v1/certs"
    x-google-audiences: "848149964201.apps.googleusercontent.com,841077041629.apps.googleusercontent.com"

Beta

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.

x-google-management

Ekstensi x-google-management mengontrol berbagai aspek pengelolaan API dan berisi kolom yang dijelaskan di bagian ini.

metrics

Anda menggunakan metrics bersama dengan kuota dan x-google-quota untuk mengonfigurasi kuota untuk API Anda. Kuota memungkinkan Anda mengontrol tingkat aplikasi yang dapat memanggil metode dalam API Anda. Contoh:

x-google-management:
  metrics:
    - name: read-requests
      displayName: Read requests
      valueType: INT64
      metricKind: DELTA

Kolom metrics berisi daftar dengan key-value pair berikut:

Elemen	Deskripsi
name	Wajib. Nama untuk metrik ini. Biasanya, ini adalah jenis permintaan (misalnya, "permintaan baca" atau "permintaan tulis") yang mengidentifikasi metrik secara unik.
displayName	Opsional, tetapi direkomendasikan. Teks yang ditampilkan untuk mengidentifikasi metrik pada tab Quotas di halaman Endpoint > Services di Konsol Google Cloud. Teks ini juga ditampilkan kepada konsumen API Anda di halaman Quotas di bagian IAM & admin dan API & Services. Nama tampilan harus maksimum 40 karakter. Agar mudah dibaca, unit dari batas kuota terkait akan otomatis ditambahkan ke nama tampilan di Konsol Google Cloud. Misalnya, jika Anda menentukan "Permintaan baca" untuk nama tampilan, "Permintaan baca per menit per project" akan ditampilkan di Konsol Google Cloud. Jika tidak ditentukan, "kuota tidak berlabel" akan ditampilkan kepada konsumen API di halaman Kuota di bagian IAM & admin dan API & Layanan. Agar nama tampilan layanan Google tetap konsisten di halaman Kuota yang dilihat konsumen API, sebaiknya gunakan hal berikut untuk nama tampilan: Gunakan "Permintaan" jika Anda hanya memiliki satu metrik. Jika Anda memiliki beberapa metrik, masing-masing metrik harus menjelaskan jenis permintaan dan berisi kata "requests" (misalnya "Permintaan baca" atau "Permintaan tulis"). Gunakan "unit kuota", bukan "permintaan", jika salah satu biaya yang terkait dengan metrik tersebut lebih besar dari 1.
valueType	Wajib. Harus INT64
metricKind	Wajib. Harus Delta

quota

Anda menentukan batas kuota untuk metrik yang ditentukan di bagian quota. Contoh:

quota:
  limits:
    - name: read-requests-limit
      metric: read-requests
      unit: 1/min/{project}
      values:
        STANDARD: 5000

Kolom quota.limits berisi daftar dengan key:value pair berikut:

Elemen	Deskripsi
name	Wajib. Nama batas, yang harus unik dalam layanan. Nama dapat berisi huruf kecil dan besar, angka, dan `-` (karakter tanda hubung), serta harus memiliki panjang maksimum 64 karakter.
metrik	Wajib. Nama metrik tempat batas ini diterapkan. Nama ini harus cocok dengan teks yang ditentukan dalam nama metrik. Jika teks yang ditentukan tidak cocok dengan nama metrik, Anda akan mendapatkan error saat men-deploy dokumen OpenAPI.
unit	Wajib. Satuan dari batas. Saat ini hanya "1/mnt/{project}" yang didukung. Artinya, batas akan diterapkan per project dan penggunaannya direset setiap menit.
nilai	Wajib. Batas untuk metrik. Anda harus menentukannya sebagai key:value pair, dalam format berikut: STANDARD: YOUR-LIMIT-FOR-THE-METRIC Anda mengganti YOUR-LIMIT-FOR-THE-METRIC dengan nilai bilangan bulat yang merupakan jumlah maksimum permintaan yang diizinkan untuk unit yang ditentukan (yang saat ini hanya per menit, per project). Contoh: values: STANDARD: 5000

x-google-quota

Ekstensi x-google-quota digunakan di bagian paths OpenAPI untuk mengaitkan metode di API dengan metrik. Metode yang tidak memiliki x-google-quota yang ditentukan tidak memiliki batas kuota yang diterapkan padanya. Contoh:

x-google-quota:
  metricCosts:
    read-requests: 1

Ekstensi x-google-quota berisi item berikut:

Elemen

Deskripsi

metricCosts

Key:value pair yang ditentukan pengguna: "YOUR-METRIC-NAME": METRIC-COST. "YOUR-METRIC-NAME": Teks untuk "YOUR-METRIC-NAME" harus cocok dengan nama metrik yang ditentukan. METRIC-COST: Nilai bilangan bulat yang menentukan biaya untuk setiap permintaan. Saat permintaan dibuat, metrik yang terkait bertambah menurut biaya yang ditentukan. Biaya memungkinkan metode untuk melakukan konsumsi dengan tarif yang berbeda dari metrik yang sama. Misalnya, jika sebuah metrik memiliki batas kuota 1.000 dan biaya 1, aplikasi panggilan dapat membuat 1.000 permintaan per menit sebelum melampaui batas tersebut. Dengan biaya 2 untuk metrik yang sama, aplikasi panggilan hanya dapat membuat 500 permintaan per menit sebelum melampaui batas.

Contoh kuota

Contoh berikut menunjukkan penambahan metrik dan batas untuk permintaan baca dan permintaan tulis.

x-google-management:
  metrics:
    # Define a metric for read requests.
    - name: "read-requests"
      displayName: "Read requests"
      valueType: INT64
      metricKind: DELTA
    # Define a metric for write requests.
    - name: "write-requests"
      displayName: "Write requests"
      valueType: INT64
      metricKind: DELTA
  quota:
    limits:
      # Rate limit for read requests.
      - name: "read-requests-limit"
        metric: "read-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000
      # Rate limit for write requests.
      - name: "write-request-limit"
        metric: "write-requests"
        unit: "1/min/{project}"
        values:
          STANDARD: 5000

paths:
  "/echo":
    post:
      description: "Echo back a given message."
      operationId: "echo"
      produces:
      - "application/json"
      responses:
        200:
          description: "Echo"
          schema:
            $ref: "#/definitions/echoMessage"
      parameters:
      - description: "Message to echo"
        in: body
        name: message
        required: true
        schema:
          $ref: "#/definitions/echoMessage"
      x-google-quota:
        metricCosts:
          read-requests: 1
      security:
      - api_key: []

x-google-api-name

Jika layanan Anda hanya berisi satu API, nama API sama dengan nama layanan Endpoint. (Endpoint menggunakan nama yang Anda tentukan di kolom host pada dokumen OpenAPI sebagai nama layanan Anda.) Jika layanan Anda berisi lebih dari satu API, tentukan nama API dengan menambahkan ekstensi x-google-api-name ke dokumen OpenAPI Anda. Ekstensi x-google-api-name memungkinkan Anda memberi nama setiap API secara eksplisit dan membuat versi independen untuk setiap API.

Misalnya, Anda dapat mengonfigurasi layanan bernama api.example.com dengan dua API, produser dan konsumen, dengan fragmen dokumen OpenAPI di bawah:

• Producer API di producer.yaml:

  swagger: 2.0
  host: api.example.com
  x-google-api-name: producer
  info:
    version: 1.0.3
  

• API Konsumen di consumer.yaml:

  swagger: 2.0
  host: api.example.com
  x-google-api-name: consumer
  info:
    version: 1.1.0
  

Anda dapat men-deploy dua dokumen OpenAPI bersama-sama dengan:

gcloud endpoints services deploy producer.yaml consumer.yaml

Catatan: Nama API harus sesuai dengan ekspresi reguler [a-z][a-z0-9]{0,39} (maks. 40 karakter, huruf kecil, tanpa simbol)