Ekstensi OpenAPI

OpenAPI   |  gRPC

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

Meskipun contoh 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 mana 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—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 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 lebih berhati-hati dalam dua hal:

• Setiap kunci API atau aturan autentikasi.
• Perutean jalur backend di layanan Anda.

Sebagai praktik terbaik, sebaiknya Anda mengonfigurasi API untuk menggunakan perutean jalur yang peka huruf besar/kecil. Dengan menggunakan perutean 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 peka huruf besar/kecil. Perilaku default bergantung pada framework yang Anda gunakan. Sebaiknya tinjau setelan di framework Anda 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 memerlukan kunci API.

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

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

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

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

Jika API Anda menggunakan perutean peka huruf besar/kecil (dan Anda belum merutekan panggilan ke "Widgets" ke kode apa pun), backend API Anda akan menampilkan 404. Namun, jika Anda menggunakan perutean 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 perutean. Lihat dokumentasi 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 teratas dan/atau tingkat operasi spesifikasi OpenAPI.

Secara default, ESP dikonfigurasi untuk memproksi semua traffic ke satu backend lokal. Alamat backend lokal ditentukan oleh --backend flag (defaultnya 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 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 berfungsi dengan ESPv2. Migrasikan 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 tanda --backend.

Catatan: Untuk ESPv2, x-google-backend dapat digunakan dengan backend lokal dengan menghilangkan 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 Endpoints untuk Serverless, backend jarak jauh harus diamankan 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 terlampir 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. Izinkan hanya 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 sudah menyetel header Authorization, 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 Authorization untuk mengambil seluruh JWT.X-Forwarded-Authorization 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 yang 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 melampirkannya 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 permintaan proxy ke backend target.

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

Jika x-google-backend digunakan di tingkat teratas spesifikasi OpenAPI, path_translation secara default adalah APPEND_PATH_TO_ADDRESS, dan jika x-google-backend digunakan di tingkat operasi spesifikasi OpenAPI, path_translation secara default adalah 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 penuh dari permintaan. Respons yang memerlukan waktu lebih lama dari batas waktu yang dikonfigurasi akan kehabisan waktu. Batas waktu default adalah 15.0 detik.

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

Batas waktu tidak dapat dinonaktifkan, tetapi dapat disetel ke angka yang tinggi —misalnya, 3600.0 untuk satu jam.

Catatan: Untuk API Gateway, nilai maksimum deadline adalah 600.

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 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. 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 mengaktifkan dukungan x-google-backend saat men-deploy penampung ESP ke GKE (contoh ini dibuat berdasarkan contoh Tutorial Endpoints 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 terjadinya terjemahan ini 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 akan 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 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 tingkat teratas 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 pelangganGoogle Cloud . Karena ID project Google Cloud bersifat unik secara global, nama domain dalam format .endpoints.PROJECT_ID.cloud.goog adalah nama domain unik untuk API Anda.

Agar 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 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 mengetahui 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 agar mendukung CORS.

Jika Anda perlu menerapkan dukungan CORS kustom dalam kode backend, tetapkan allowCors: True agar 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 set kunci publik penyedia untuk memvalidasi tanda tangan JSON Web Token.

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

• Format set 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/securetoken@"
  

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

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

Perhatikan bahwa menghilangkan x-google-jwks_uri akan menghasilkan waktu cold start yang lebih tinggi, karena ESP harus melakukan panggilan jarak jauh tambahan saat startup. Oleh karena itu, sebaiknya kolom ini dihilangkan hanya jika JWKS URI 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 cara meneruskan JWT.

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

Catatan: Jika Anda menentukan ekstensi x-google-jwt-locations, Endpoints 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 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 bermigrasi 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 JWT aud harus cocok dengan kolom host dalam dokumen OpenAPI, kecuali jika tanda --disable_jwt_audience_service_name_check digunakan. Jika tanda digunakan dan x-google-audiences tidak ditentukan, kolom JWT aud 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 dari 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 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 Kuota pada halaman Endpoints > Services di Google Cloud konsol. Teks ini juga ditampilkan kepada konsumen 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 yang terkait akan otomatis ditambahkan ke nama tampilan di konsolGoogle Cloud . Misalnya, jika Anda menentukan "Permintaan baca" untuk nama tampilan, maka "Permintaan baca per menit per project" akan ditampilkan di konsolGoogle Cloud . Jika tidak ditentukan, "kuota tidak berlabel" akan ditampilkan kepada konsumen API Anda di halaman Kuota di bagian IAM & admin dan API & Layanan. Untuk menjaga konsistensi dengan nama tampilan layanan Google yang tercantum di halaman Kuota yang dilihat konsumen API Anda, sebaiknya gunakan nama tampilan berikut: 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" dan 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 dapat berisi huruf kecil dan huruf besar, angka, dan `-` (karakter tanda hubung), serta harus memiliki panjang maksimum 64 karakter.
metrik	Wajib. Nama metrik yang berlaku untuk 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. Unit 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 key:value, 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 Anda 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

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 untuk menggunakan data dengan kecepatan yang berbeda dari metrik yang sama. Misalnya, jika metrik memiliki batas kuota 1.000 dan biaya 1, aplikasi yang memanggil 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 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 Endpoints. (Endpoints 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 Anda. 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, producer dan consumer, 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 dua dokumen OpenAPI secara bersamaan dengan:

gcloud endpoints services deploy producer.yaml consumer.yaml

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