Memodifikasi Cloud Endpoints untuk menggunakan OpenAPI 3.x

Halaman ini menjelaskan cara menggunakan spesifikasi OpenAPI 3.x saat mengonfigurasi Endpoints.

Sebelum memulai

  • Pastikan Anda memiliki instance Endpoints yang sudah ada dan dikonfigurasi dengan spesifikasi OpenAPI 2.0.
  • Instal gcloud CLI. Untuk mengetahui informasi selengkapnya, lihat Menginstal Google Cloud CLI.

Ubah konfigurasi Endpoints untuk menggunakan OpenAPI 3.x

Selesaikan langkah-langkah berikut untuk mengubah konfigurasi Endpoints OpenAPI 2.0 yang ada agar menggunakan OpenAPI 3.x.

Melihat histori deployment

Untuk melihat histori deployment:

  1. Di konsol Google Cloud , buka halaman Endpoints > Services.

    Buka halaman Endpoints Services

  2. Dari daftar project, pilih project Anda.

  3. Jika Anda memiliki lebih dari satu API, pilih API dari daftar.

  4. Untuk melihat daftar deployment konfigurasi layanan, klik tab Histori deployment. Daftar menampilkan:

    • ID konfigurasi.
    • Tanggal konfigurasi layanan di-deploy.
    • Siapa yang men-deploy konfigurasi layanan.

Melihat konfigurasi layanan

Di tab Histori penerapan, pilih penerapan terbaru dari daftar. Isi file konfigurasi layanan yang di-deploy akan ditampilkan.

Mengonversi dokumen OpenAPI ke OpenAPI 3.x

Konversikan dokumen OpenAPI 2.0 Anda ke OpenAPI 3.x. Anda dapat menggunakan alat yang mendukung konversi ini ke OpenAPI 3.x. Misalnya, Swagger Editor menyediakan utilitas konversi.

Setelah konversi awal ke OpenAPI 3.x, terapkan perubahan tambahan secara manual pada dokumen agar sesuai dengan OpenAPI 3.x dan pastikan kompatibilitas dengan ekstensi dan fitur Endpoints.

Tabel berikut menjelaskan perubahan yang diperlukan:

Fitur OpenAPI 2.0 OpenAPI 3.x Deskripsi perubahan
Kunci API securityDefinitions securitySchemes Kunci API menggunakan dukungan kunci API OpenAPI langsung. Alat konversi biasanya menanganinya secara otomatis. Tidak diperlukan perubahan manual.
Autentikasi JWT x-google-audiences, dll. x-google-auth Di ekstensi OpenAPI 2.0, Anda menentukan konfigurasi OAuth dengan ekstensi individual pada instance securityDefinition. Alat konversi mengonversi instance skema keamanan ke #/components/securitySchemes dan membiarkan ekstensi. Ubah ekstensi ini secara manual agar menjadi turunan dari x-google-auth dan hapus awalan x-google-. Nilainya tetap sama.
Kuota x-google-management, x-google-quota x-google-api-management, x-google-quota Dalam ekstensi OpenAPI 2.0, Anda menentukan metrik dan kuota di x-google-management dan melampirkannya dengan x-google-quota. Alat konversi akan tetap menggunakan ekstensi ini. Pindahkan konfigurasi metrik dan kuota secara manual dari x-google-management ke x-google-api-management. Ubah konfigurasi untuk menggunakan kunci YAML, dan hapus valueType, metricKind, dan unit. Menghapus metricCosts dari instance x-google-quota.
Backend x-google-backend x-google-api-management, x-google-backend Di ekstensi OpenAPI 2.0, Anda menentukan backend di x-google-backend, dan konfigurasi berlaku jika ditetapkan. Di ekstensi OpenAPI 3.x, Anda menentukan backend di x-google-api-management, lalu menerapkannya dengan x-google-backend. Alat konversi akan membiarkan ekstensi ini tetap ada. Pindahkan konfigurasi secara manual ke x-google-api-management. Ubah instance x-google-backend untuk mereferensikan konfigurasi tersebut.
Endpoint x-google-endpoints x-google-endpoint, servers Dalam ekstensi OpenAPI 2.0, Anda menentukan konfigurasi endpoint di x-google-endpoints. Di ekstensi OpenAPI 3.x, Anda menggunakan x-google-endpoint, tetapi ini adalah ekstensi di servers, bukan di root. Alat konversi akan tetap membiarkan ekstensi ini. Pindahkan secara manual ke servers dan hapus kolom name. Contoh: 
# OpenAPI 2.0
x-google-endpoints:
- name: "my-api.apigateway.my-project.cloud.goog"
  allowCors: True
# OpenAPI 3.x
servers:
- url: https://my-api.apigateway.my-project.cloud.goog/
  x-google-endpoint:
    allowCors: True
Nama API x-google-api-name x-google-api-management Dalam ekstensi OpenAPI 2.0, Anda menentukan nama API di x-google-api-name. Di ekstensi OpenAPI 3.x, Anda menggunakan kolom apiName di x-google-api-management. Pindahkan konfigurasi ini secara manual ke x-google-api-management.
Izinkan semua traffic x-google-allow NOT SUPPORTED Hapus ini dari dokumen OpenAPI. Endpoints tidak mendukungnya di OpenAPI 3.x.

Men-deploy ulang konfigurasi layanan Anda

Setiap kali Anda mengubah sesuatu dalam dokumen OpenAPI, pastikan untuk men-deploy-nya lagi agar Endpoints memiliki konfigurasi layanan API versi terbaru. Anda tidak perlu men-deploy ulang atau memulai ulang ESP jika sebelumnya men-deploy ESP dengan opsi rollout disetel ke managed. Opsi ini mengonfigurasi ESP untuk menggunakan konfigurasi layanan yang di-deploy terbaru. Saat Anda menentukan opsi ini, hingga 5 menit setelah Anda men-deploy konfigurasi layanan baru, ESP akan mendeteksi perubahan dan otomatis mulai menggunakannya. Sebaiknya tentukan opsi ini, bukan ID konfigurasi tertentu yang akan digunakan ESP.

Untuk men-deploy dokumen OpenAPI:

  1. Ubah direktori ke lokasi yang berisi dokumen OpenAPI Anda.

  2. Validasi project ID yang ditampilkan dari perintah berikut untuk memastikan bahwa layanan tidak dibuat di project yang salah.

    gcloud config list project

    Jika Anda perlu mengubah project default, jalankan perintah berikut dan ganti YOUR_PROJECT_ID dengan Google Cloud project ID tempat Anda ingin membuat layanan::

    gcloud config set project <var>YOUR_PROJECT_ID</var>

  3. Jalankan perintah berikut, dan ganti YOUR_OPENAPI_DOCUMENT dengan nama dokumen OpenAPI yang mendeskripsikan API Anda:

    gcloud endpoints services deploy <var>YOUR_OPENAPI_DOCUMENT</var>

Saat pertama kali Anda menjalankan perintah sebelumnya, Service Management akan membuat layanan Endpoints baru di project default dengan nama yang cocok dengan teks yang Anda tentukan di kolom host dalam dokumen OpenAPI Anda dan mengupload konfigurasi layanan Anda.

Saat membuat dan mengonfigurasi layanan, Service Management akan menampilkan informasi ke terminal. Setelah berhasil diselesaikan, Anda akan melihat baris seperti berikut yang menampilkan ID konfigurasi layanan dan nama layanan:

Service Configuration [2017-02-13r0] uploaded for service [echo-api.endpoints.example-project-12345.cloud.goog]

Dalam contoh sebelumnya, 2017-02-13r0 adalah ID konfigurasi layanan dan echo-api.endpoints.example-project-12345.cloud.goog adalah nama layanan.

Setelah deployment berhasil, Anda dapat melihat API di halaman Endpoints > Services di konsol Google Cloud .

Jika Anda menerima pesan error, lihat Pemecahan Masalah Konfigurasi dan Deployment Endpoint.

Langkah berikutnya