Ekstensi OpenAPI 2.0 di API Gateway

API Gateway menerima serangkaian ekstensi khusus Google untuk spesifikasi OpenAPI yang mengonfigurasi perilaku gateway. Halaman ini menjelaskan ekstensi khusus Google pada spesifikasi OpenAPI 2.0 yang digunakan untuk mengonfigurasi perilaku API Gateway seperti perutean backend, autentikasi, dan fitur pengelolaan API.

Meskipun contoh yang diberikan 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 API Gateway.

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 API Gateway.

Jika all digunakan, panggilan yang tidak dikonfigurasi —dengan atau tanpa kunci API atau autentikasi pengguna—akan diteruskan melalui API Gateway ke API Anda.

API Gateway memproses panggilan ke API Anda dengan memperhatikan huruf besar/kecil. Misalnya, API Gateway 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 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 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 mewajibkan kunci API.

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

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

Karena Widgets tidak tercantum dalam spesifikasi OpenAPI Anda, API Gateway 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 jarak jauh. Ekstensi dapat ditentukan di tingkat teratas, tingkat operasi, atau kedua tingkat spesifikasi OpenAPI.

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

Ekstensi x-google-backend berisi kolom berikut:

address

address: URL

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

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

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, API Gateway akan otomatis menetapkan jwt_audience secara default agar cocok dengan address. Jika address tidak ditetapkan, Gateway API akan otomatis menetapkan disable_auth ke true.

jwt_audience

jwt_audience: string

Opsional. Audiens JWT yang ditentukan saat API Gateway mendapatkan token ID instance, yang kemudian digunakan saat membuat permintaan backend target.

Saat mengonfigurasi API Gateway untuk Serverless, backend jarak jauh harus diamankan agar hanya mengizinkan traffic dari API Gateway. API Gateway akan melampirkan token ID instance ke header Authorization saat memproksi permintaan. Token ID instance mewakili akun layanan runtime yang digunakan untuk men-deploy API Gateway. Backend jarak jauh kemudian dapat memverifikasi bahwa permintaan berasal dari API Gateway berdasarkan token yang dilampirkan ini.

Misalnya, backend jarak jauh yang di-deploy di Cloud Run dapat menggunakan Identity and Access Management (IAM) untuk:

  1. Membatasi pemanggilan yang tidak diautentikasi dengan mencabut roles/run.invoker dari principal allUsers khusus.
  2. Izinkan hanya API Gateway untuk memanggil backend dengan memberikan peran roles/run.invoker ke akun layanan runtime API Gateway.

Secara default, API Gateway 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 Identity-Aware Proxy (IAP), Anda harus mengganti audiens JWT. App Engine dan IAP menggunakan client ID OAuth-nya sebagai audiens yang diharapkan.

Jika fitur ini diaktifkan, API Gateway akan mengubah header dalam permintaan. Jika permintaan sudah menyetel header Authorization, API Gateway 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 Gateway API harus menggunakan header Authorization untuk mengambil seluruh JWT.X-Forwarded-Authorization Backend harus memverifikasi JWT di header ini, karena API Gateway tidak akan melakukan verifikasi jika metode autentikasi tidak dikonfigurasi.

Untuk contoh konfigurasi, lihat Membuat konfigurasi API.

disable_auth

disable_auth: bool

Opsional. Properti ini menentukan apakah API Gateway 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 API Gateway 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 API Gateway saat memproksi permintaan 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 dipatuhi. API Gateway akan otomatis menggunakan nilai default dalam kasus ini.

Batas waktu tidak dapat dinonaktifkan, tetapi dapat disetel ke angka yang tinggi —misalnya, 600 detik (batas waktu maksimum).

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

Memahami terjemahan jalur

Saat menangani permintaan, API Gateway 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, sebagaimana 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 API Gateway 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 API Gateway untuk mengetahui informasi tentang cara mengonfigurasi API Gateway agar mendukung CORS.

Jika Anda perlu menerapkan dukungan CORS kustom dalam kode backend, tetapkan allowCors: True agar API Gateway 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.

Kolom x-google-jwks_uri (OpenAPI 2.0) atau jwksUri (OpenAPI 3.x) diperlukan. API Gateway mendukung dua format kunci publik asimetris yang ditentukan oleh ekstensi OpenAPI ini:

  • Format set JWK. Contoh:

    OpenAPI 2.0

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

    OpenAPI 3.x

    jwksUri: "https://YOUR_ACCOUNT_NAME.YOUR_AUTH_PROVIDER_URL/.well-known/jwks.json"
  • X509. Contoh:

    OpenAPI 2.0

    x-google-jwks_uri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

    OpenAPI 3.x

    jwksUri: "https://www.googleapis.com/service_accounts/v1/metadata/x509/securetoken@system.gserviceaccount.com"

Jika Anda menggunakan format kunci simetris, tetapkan x-google-jwks_uri (OpenAPI 2.0) atau jwksUri (OpenAPI 3.x) ke URI file yang berisi string kunci berenkode base64url.

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.

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

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 "

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 di dokumen OpenAPI.

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"

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, "permintaan baca" atau "permintaan tulis") yang secara unik mengidentifikasi metrik.
displayName

Opsional, tetapi direkomendasikan. Teks yang ditampilkan untuk mengidentifikasi metrik di tab Kouta pada halaman Endpoint > Layanan di Google Cloud konsol. Teks ini juga ditampilkan kepada konsumen API Anda di halaman Quotas di bagian IAM & admin dan APIs & Services. 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 konsol.Google Cloud Jika tidak ditentukan, "kuota tidak berlabel" akan ditampilkan kepada konsumen API Anda di halaman Quotas di bagian IAM & admin dan APIs & Services.

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. Satuan batas. 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 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 API Gateway. (API Gateway menggunakan nama yang Anda tentukan di kolom host dokumen OpenAPI sebagai nama layanan Anda.) Jika layanan Anda berisi lebih dari satu API, Anda dapat menentukan nama API dengan menambahkan ekstensi x-google-api-name ke dokumen OpenAPI Anda. Ekstensi x-google-api-name memungkinkan Anda memberi nama API satu per satu 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 yang ditampilkan di sini:

  • 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 api-gateway api-configs create API_CONFIG_ID \
  --api=my-api \
  --openapi-spec="producer.yaml,consumer.yaml" \
  --project=my-project-id