Ekstensi OpenAPI

OpenAPI   |  gRPC

Cloud Endpoints menerima serangkaian ekstensi khusus Google ke spesifikasi OpenAPI yang mengonfigurasi perilaku Extensible Service Proxy (ESP), Extensible Service Proxy V2 (ESPv2), 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 ditayangkan melalui ESP.

Saat all digunakan, panggilan yang tidak dikonfigurasi—dengan atau tanpa kunci API atau autentikasi pengguna—akan diteruskan melalui 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 diteruskan, terlepas dari properti x-google-allow.

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

Saat all digunakan, Anda harus lebih berhati-hati dalam dua area:

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

Sebagai praktik terbaik, sebaiknya konfigurasikan API Anda untuk menggunakan pemilihan rute jalur yang peka huruf besar/kecil. Dengan menggunakan pemilihan rute yang peka huruf besar/kecil, API Anda akan menampilkan kode status HTTP 404 saat metode yang diminta di 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 pemilihan rute yang peka huruf besar/kecil. Perilaku default bergantung pada framework yang Anda gunakan. Sebaiknya Anda meninjau setelan di framework untuk memastikan pemilihan rute peka huruf besar/kecil 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 Widgets.
• Anda telah mengonfigurasi spesifikasi OpenAPI untuk 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 Anda, ESP akan meneruskan permintaan berikut ke layanan Anda tanpa kunci API:

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

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

Bahasa dan framework yang berbeda memiliki metode yang berbeda untuk mengontrol sensitivitas huruf besar/kecil dan pemilihan rute. Lihat dokumentasi untuk framework Anda untuk mengetahui detailnya.

x-google-backend

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

Secara default, ESP dikonfigurasi untuk melakukan proxy semua traffic ke satu backend lokal. Alamat backend lokal ditentukan oleh flag --backend (defaultnya 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 berdasarkan 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 akan berfungsi dengan ESPv2. Harap migrasi ke ESPv2 untuk menggunakan fitur baru. Fitur yang tidak didukung oleh ESP didokumentasikan berdasarkan 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 salah 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 secara default agar cocok dengan address. Jika address tidak ditetapkan, ESPv2 akan otomatis menetapkan disable_auth ke true.

jwt_audience

jwt_audience: string

Opsional. Audiens JWT yang ditentukan saat ESPv2 mendapatkan 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 dilindungi agar hanya mengizinkan traffic dari ESPv2. ESPv2 akan melampirkan token ID instance ke header Authorization saat melakukan proxy permintaan. Token ID instance mewakili akun layanan runtime yang digunakan untuk men-deploy ESPv2. Backend jarak jauh kemudian dapat memverifikasi bahwa permintaan berasal dari ESPv2 berdasarkan token yang dilampirkan 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 entity 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 dengan 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 mereka sebagai audiens yang diharapkan.

Jika fitur ini diaktifkan, ESPv2 akan mengubah header dalam permintaan. Jika permintaan memiliki header Authorization yang sudah ditetapkan, 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 mengetahui detail selengkapnya.

disable_auth

disable_auth: bool

Opsional. Properti ini menentukan apakah ESPv2 harus mencegah mendapatkan token ID instance dan mencegah melampirkan token tersebut ke permintaan.

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

1. Backend harus mengizinkan pemanggilan tanpa autentikasi.
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 tingkat teratas spesifikasi OpenAPI, path_translation akan ditetapkan secara default ke APPEND_PATH_TO_ADDRESS, dan saat x-google-backend digunakan di tingkat operasi spesifikasi OpenAPI, path_translation akan 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 waktunya. Batas waktu default adalah 15.0 detik.

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

Batas waktu tidak dapat dinonaktifkan, tetapi dapat disetel ke angka 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. Batas waktu yang singkat dapat menyebabkan beberapa permintaan yang lebih mahal gagal secara konsisten. Seimbangkan batasan ini untuk memilih batas waktu yang baik.

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. Ini adalah opsi yang 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 tempat Anda tidak mengontrol opsi penampung ESP, opsi ini sudah disediakan untuk Anda.) Berikut adalah contoh cara mengaktifkan dukungan x-google-backend saat men-deploy penampung ESP ke GKE (contoh ini dibuat berdasarkan contoh Tutorial Endpoint di 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

Saat menangani permintaan, ESP akan mengambil jalur permintaan asli dan menerjemahkannya sebelum membuat permintaan ke backend target. Cara tepat terjemahan ini terjadi bergantung pada strategi terjemahan jalur yang Anda gunakan. Ada dua strategi terjemahan 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 ekstensi x-google-backend. Jika jalur OpenAPI yang sesuai 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 Endpoints di domain cloud.goog dengan menambahkan hal berikut ke dokumen OpenAPI:

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

Tambahkan ekstensi x-google-endpoints di tingkat 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 digunakan bersama 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 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 telah Anda tentukan di kolom host.
• Data A DNS yang menggunakan nama dan alamat IP yang Anda konfigurasikan 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 di 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 untuk mendukung CORS.

Jika Anda perlu menerapkan 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 teratas 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. Nilai dapat berupa nama host atau alamat email.

x-google-jwks_uri

x-google-jwks_uri: URI

URI kumpulan kunci publik penyedia 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 menghilangkan x-google-jwks_uri, ESP akan mengikuti protokol OpenID Connect Discovery untuk menemukan URI JWKS secara otomatis untuk penyedia OpenID tertentu. ESP akan membuat permintaan ke x-google-issuer/.well-known/openid-configuration, menguraikan respons JSON, dan membaca URI JWKS dari kolom jwks_uri tingkat atas.

Perhatikan bahwa menghilangkan x-google-jwks_uri akan menghasilkan waktu cold start yang lebih tinggi, karena ESP harus melakukan panggilan jarak jauh tambahan saat memulai. Oleh karena itu, sebaiknya hapus kolom ini jika URI JWKS sering berubah. Sebagian besar penyedia OpenID bersertifikasi (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 terautentikasi ke Endpoints API untuk mengetahui contoh tentang cara meneruskan JWT.

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

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. Saat 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 sebagian 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: Fitur ini saat ini tidak didukung oleh ESP. Harap migrasikan 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 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 flag digunakan dan x-google-audiences tidak ditentukan, kolom aud JWT tidak 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 quota dan x-google-quota untuk mengonfigurasi kuota API. Kuota memungkinkan Anda mengontrol kecepatan aplikasi dapat memanggil metode di 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
nama	Wajib. Nama untuk metrik ini. Biasanya, ini adalah jenis permintaan (misalnya, "read-requests" atau "write-requests") yang secara unik mengidentifikasi metrik.
displayName	Opsional, tetapi direkomendasikan. Teks yang ditampilkan untuk mengidentifikasi metrik di tab Quotas di halaman Endpoints > Services di konsol Google Cloud. Teks ini juga ditampilkan kepada pengguna API Anda di halaman Kuota di bagian IAM & admin dan API & Layanan. Nama tampilan harus maksimal 40 karakter. Untuk tujuan keterbacaan, unit dari batas kuota terkait 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 tanpa label" akan ditampilkan kepada konsumen API Anda di halaman Kuota di bagian IAM & admin dan API & Layanan. Untuk mempertahankan konsistensi dengan nama tampilan layanan Google yang tercantum di halaman Kuota yang dilihat konsumen API Anda, kami merekomendasikan hal berikut untuk nama tampilan: Gunakan "Permintaan" jika Anda hanya memiliki satu metrik. Jika Anda memiliki beberapa metrik, setiap metrik harus menjelaskan jenis permintaan dan berisi kata "permintaan" (misalnya "Permintaan baca" atau "Permintaan tulis"). Gunakan "unit kuota", bukan "permintaan" jika salah satu biaya yang terkait dengan metrik lebih besar dari 1.
valueType	Wajib. Harus berupa 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
nama	Wajib. Nama batas, yang harus unik dalam layanan. Nama tersebut dapat berisi huruf besar dan kecil, angka, dan `-` (karakter tanda hubung), dan harus memiliki panjang maksimum 64 karakter.
metrik	Wajib. Nama metrik yang dikenai batas ini. 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 batas. Saat ini, hanya "1/min/{project}" yang didukung, yang berarti batas diterapkan per project dan penggunaan direset setiap menit.
nilai	Wajib. Batas untuk metrik. Anda harus menentukannya sebagai pasangan kunci:nilai, 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). Misalnya: values: STANDARD: 5000

x-google-quota

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

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

Ekstensi x-google-quota berisi item berikut:

Elemen

Deskripsi

metricCosts

Pasangan nilai kunci 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 terkait akan bertambah dengan biaya yang ditentukan. Biaya memungkinkan metode menggunakan dengan tarif yang berbeda dari metrik yang sama. Misalnya, jika metrik memiliki batas kuota 1.000 dan biaya 1, aplikasi panggilan dapat membuat 1.000 permintaan per menit sebelum melampaui batas. Dengan biaya 2 untuk metrik yang sama, aplikasi panggilan hanya dapat membuat 500 permintaan per menit sebelum melebihi 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 akan sama dengan nama layanan Endpoint. (Endpoint menggunakan nama yang Anda tentukan di kolom host dokumen OpenAPI sebagai nama layanan Anda.) Jika layanan Anda berisi lebih dari satu API, Anda menentukan nama API dengan menambahkan ekstensi x-google-api-name ke dokumen OpenAPI. Ekstensi x-google-api-name memungkinkan Anda memberi nama setiap API secara eksplisit dan menetapkan pembuatan 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
  

• Consumer API di consumer.yaml:

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

Anda dapat men-deploy kedua dokumen OpenAPI secara bersamaan 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)