Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
OpenAPI | gRPC
Halaman ini memberikan prosedur konfigurasi dan deployment mendetail untuk mengubah
nomor versi API Anda. Prosedur yang Anda gunakan bergantung pada apakah
perubahan pada API Anda kompatibel dengan versi lama.
Jika versi API baru Anda memiliki perubahan yang kompatibel dengan versi lama, seperti menambahkan kolom atau metode baru, lihat
Perubahan yang kompatibel dengan versi lama.
Jika API baru Anda memiliki perubahan pada metode yang ada yang merusak kode klien
pelanggan, lihat
Perubahan inkompatibilitas mundur.
Saat Anda membuat perubahan pada API yang kompatibel dengan versi sebelumnya
kode klien yang ada, sebagai praktik terbaik, tambahkan nomor versi minor
API Anda sebelum men-deploy versi baru. Meskipun Cloud Endpoints hanya menjalankan satu versi minor API dalam satu waktu, grafik dan log di Endpoints > Services akan menampilkan nomor versi. Dengan menambahkan
nomor versi minor sebelum Anda men-deploy, grafik dan log akan memberikan histori deployment Anda yang berlabel.
Untuk menambahkan nomor versi minor:
Di openapi.yaml, tambahkan nomor versi minor dari
kolom info.version. Misalnya, jika versi saat ini adalah 1.1, tetapkan
info.version ke 1.2:
info:description:"A simple Cloud Endpoints API example."title:"Endpoints Example"version:"1.2"host:"echo-api.endpoints.example-project-12345.cloud.goog"
Gunakan Google Cloud CLI untuk men-deploy konfigurasi API:
gcloud endpoints services deploy openapi.yaml
Deploy backend API menggunakan ID konfigurasi yang ditampilkan dari
langkah sebelumnya. Untuk mengetahui detailnya, lihat
Men-deploy backend API.
Perubahan yang tidak kompatibel dengan versi lama
Saat Anda membuat perubahan pada API yang merusak kode klien
pelanggan, sebagai praktik terbaik, tambahkan nomor versi utama API Anda.
Endpoint dapat menjalankan lebih dari satu versi utama API secara serentak. Dengan menyediakan kedua versi API, pelanggan Anda dapat memilih
versi yang ingin digunakan dan dikontrol saat mereka bermigrasi ke versi baru.
Untuk menjalankan versi API yang ada dan baru secara serentak:
Buat file konfigurasi OpenAPI terpisah untuk setiap versi yang perlu Anda tayangkan. Prosedur ini menggunakan nama file openapi-v1.yaml dan
openapi-v2.yaml sebagai contoh.
Salin konten openapi-v1.yaml ke openapi-v2.yaml.
Di openapi-v1.yaml, konfigurasikan hal berikut:
Tetapkan kolom info.version ke nomor versi yang ada.
Jangan ubah kolom basePath.
Contoh:
info:description:"A simple Cloud Endpoints API example."title:"Endpoints Example"version:"1.1"host:"echo-api.endpoints.example-project-12345.cloud.goog"basePath:"/v1"
Di openapi-v2.yaml, konfigurasikan hal berikut:
Membuat perubahan yang tidak kompatibel dengan versi lama.
Tetapkan kolom info.version ke nomor versi baru.
Tetapkan kolom basePath untuk menyertakan nomor versi utama baru.
Hapus bagian x-google-endpoints. Bagian ini diperlukan jika Anda
ingin menentukan alamat IP DNS atau flag allowCors. Saat men-deploy dua versi API dengan dua file konfigurasi yaml, hanya satu dari keduanya yang dapat memiliki x-google-endpoints, tetapi konfigurasinya akan berlaku untuk kedua versi.
Contoh:
info:description:"A simple Google Cloud Endpoints API example."title:"Endpoints Example"version:"2.0"host:"echo-api.endpoints.example-project-12345.cloud.goog"basePath:"/v2"
Gunakan Google Cloud CLI untuk men-deploy kedua file konfigurasi API:
Deploy satu backend yang menayangkan kedua versi API menggunakan
ID konfigurasi yang ditampilkan dari langkah sebelumnya. Untuk mengetahui detailnya, lihat
Men-deploy backend API.
[[["Mudah dipahami","easyToUnderstand","thumb-up"],["Memecahkan masalah saya","solvedMyProblem","thumb-up"],["Lainnya","otherUp","thumb-up"]],[["Sulit dipahami","hardToUnderstand","thumb-down"],["Informasi atau kode contoh salah","incorrectInformationOrSampleCode","thumb-down"],["Informasi/contoh yang saya butuhkan tidak ada","missingTheInformationSamplesINeed","thumb-down"],["Masalah terjemahan","translationIssue","thumb-down"],["Lainnya","otherDown","thumb-down"]],["Terakhir diperbarui pada 2025-09-08 UTC."],[[["\u003cp\u003eThis document outlines procedures for updating API versions, differentiating between backwards-compatible and backwards-incompatible changes.\u003c/p\u003e\n"],["\u003cp\u003eFor backwards-compatible changes, it's recommended to increment the minor version number in the \u003ccode\u003einfo.version\u003c/code\u003e field of the \u003ccode\u003eopenapi.yaml\u003c/code\u003e file and then deploy using the Google Cloud CLI.\u003c/p\u003e\n"],["\u003cp\u003eWhen introducing backwards-incompatible changes, it's recommended to increment the major version number and create separate OpenAPI configuration files for each version.\u003c/p\u003e\n"],["\u003cp\u003eTo deploy multiple major versions concurrently, each version should have its own configuration file (e.g., \u003ccode\u003eopenapi-v1.yaml\u003c/code\u003e, \u003ccode\u003eopenapi-v2.yaml\u003c/code\u003e) with distinct \u003ccode\u003ebasePath\u003c/code\u003e values and the \u003ccode\u003ex-google-endpoints\u003c/code\u003e section removed from all but one configuration.\u003c/p\u003e\n"],["\u003cp\u003eAfter the deployment of the API configuration files, a single backend must be deployed that services both versions of the API.\u003c/p\u003e\n"]]],[],null,["# Versioning an API\n\nOpenAPI \\| gRPC\n\n\u003cbr /\u003e\n\nThis page provides detailed configuration and deployment procedures for changing\nthe version number of your API. The procedure that you use depends on whether\nthe changes to your API are backwards compatible.\n\n- If your new API version has backwards-compatible changes, such as adding new fields or methods, see [Backwards-compatible changes](#backwards-compatible).\n- If your new API has changes to an existing method that breaks your customers' client code, see [Backwards-incompatible changes](#backwards-incompatible).\n\nFor additional information and best practices, see\n[API lifecycle management](/endpoints/docs/openapi/lifecycle-management).\n\nBackwards-compatible changes\n----------------------------\n\nWhen you make changes to your API that are backwards compatible with\nexisting client code, as a best practice, increment the minor version number of\nyour API before you deploy the new version. Although Cloud Endpoints runs only\none minor version of an API at a time, the graphs and logs in\n**Endpoints** \\\u003e **Services** display the version number. By incrementing the\nminor version number before you deploy, the graphs and logs provide a labeled\nhistory of your deployments.\n\nTo increment the minor version number:\n\n1. In `openapi.yaml`, increment the minor version number of the\n `info.version` field. For example, if the current version is `1.1`, set\n `info.version` to `1.2`:\n\n info:\n description: \"A simple Cloud Endpoints API example.\"\n title: \"Endpoints Example\"\n version: \"1.2\"\n host: \"echo-api.endpoints.example-project-12345.cloud.goog\"\n\n2. Use the Google Cloud CLI to deploy the API configuration:\n\n gcloud endpoints services deploy openapi.yaml\n\n3. Deploy the API backend by using the configuration ID returned from the\n previous step. For details, see\n [Deploying the API backend](/endpoints/docs/openapi/deploy-api-backend).\n\nBackwards-incompatible changes\n------------------------------\n\nWhen you make changes to your API that breaks your customers' client\ncode, as a best practice, increment the major version number of your API.\nEndpoints can run more than one major version of an API\nconcurrently. By providing both versions of the API, your customers can pick\nwhich version they want to use and control when they migrate to the new version.\n\nTo run the existing and new versions of an API concurrently:\n\n1. Create separate OpenAPI configuration files for each version you need to\n serve. This procedure uses the file names `openapi-v1.yaml` and\n `openapi-v2.yaml` for example purposes.\n\n2. Copy the contents of `openapi-v1.yaml` to `openapi-v2.yaml`.\n\n3. In `openapi-v1.yaml` configure the following:\n\n - Set the `info.version` field to the existing version number.\n - Leave the `basePath` field unchanged.\n\n For example: \n\n info:\n description: \"A simple Cloud Endpoints API example.\"\n title: \"Endpoints Example\"\n version: \"1.1\"\n host: \"echo-api.endpoints.example-project-12345.cloud.goog\"\n basePath: \"/v1\"\n\n4. In `openapi-v2.yaml` configure the following:\n\n - Make backwards-incompatible changes.\n - Set the `info.version` field to the new version number.\n - Set the `basePath` field to include the new major version number.\n - Remove the `x-google-endpoints` section. This section is needed if you want to specify DNS IP address or `allowCors` flag. When deploying two versions of the API with two yaml config files, only one of them can have `x-google-endpoints`, but its config will apply to both versions.\n\n For example: \n\n info:\n description: \"A simple Google Cloud Endpoints API example.\"\n title: \"Endpoints Example\"\n version: \"2.0\"\n host: \"echo-api.endpoints.example-project-12345.cloud.goog\"\n basePath: \"/v2\"\n\n5. Use the Google Cloud CLI to deploy both API configuration files:\n\n gcloud endpoints services deploy openapi-v1.yaml openapi-v2.yaml\n\n | **Note:** Cloud Endpoints internally converts your multiple OpenAPI configuration files into a single configuration, which is identified by one configuration ID.\n6. Deploy a single backend that serves both versions of the API by using the\n configuration ID returned from the previous step. For details, see\n [Deploying the API backend](/endpoints/docs/openapi/deploy-api-backend).\n\nWhat's next\n-----------\n\n- [API lifecycle management](/endpoints/docs/openapi/lifecycle-management)\n- [Planning your Google Cloud projects](/endpoints/docs/openapi/planning-cloud-projects)"]]
