Bermigrasi ke Cloud Endpoints Frameworks versi 2.0
Tetap teratur dengan koleksi
Simpan dan kategorikan konten berdasarkan preferensi Anda.
Framework Cloud Endpoints sebelumnya disebut Endpoints. Untuk membedakan kedua versi tersebut, halaman ini menyebut versi baru sebagai Endpoints Frameworks versi 2.0, dan versi lama sebagai Endpoints versi 1.0. Halaman ini menjelaskan cara memigrasikan aplikasi Cloud Endpoints versi 1.0 ke Endpoints Frameworks versi 2.0.
Migrasi terdiri dari perubahan library dan perubahan konfigurasi
aplikasi, tetapi Anda tidak perlu melakukan perubahan apa pun pada kode.
Manfaat
Endpoint versi 2.0 memberikan sejumlah manfaat, termasuk:
Mengurangi latensi permintaan.
Integrasi yang lebih baik dengan fitur App Engine, seperti domain kustom.
Fitur pengelolaan API baru.
Endpoints Frameworks versi 2.0 tidak memengaruhi antarmuka ke API Anda. Klien yang ada akan terus berfungsi setelah migrasi tanpa perubahan kode sisi klien.
Ringkasan fitur
Fitur berikut kompatibel dengan Endpoints
versi 1.0:
Protokol JSON-REST, yang digunakan oleh semua library klien Google
Layanan penemuan
Semua fitur autentikasi yang ada (OAuth2/OpenID Connect)
Dukungan library klien untuk klien yang dibuat
CORS (untuk pemanggil JavaScript yang tidak menggunakan library klien JavaScript Google)
API Explorer
Pemisahan traffic tidak tersedia.
Fitur yang saat ini dikecualikan
Fitur berikut tidak tersedia. Jika Anda memerlukan salah satu fitur tersebut,
kirimkan
permintaan fitur.
Periksa string versi API Anda. String versi Anda, yang ditentukan dalam
dekorator @endpoints.api(version='v1', ...), akan muncul di jalur API Anda.
Jika Anda menentukan string versi yang kompatibel dengan
standar SemVer,
hanya nomor versi utama yang akan muncul di jalur API saat Anda men-deploy
API. Misalnya, API yang disebut echo dengan versi 2.1.0 akan
memiliki jalur seperti /echo/v2. Jika Anda mengupdate API echo ke versi
2.2.0 dan men-deploy perubahan yang kompatibel dengan versi lama, jalurnya tetap /echo/v2.
Hal ini memungkinkan Anda memperbarui nomor versi API saat membuat perubahan yang kompatibel dengan versi lama tanpa merusak jalur yang ada untuk klien Anda.
Namun, jika Anda mengupdate echo API ke versi 3.0.0 (karena Anda
men-deploy perubahan yang dapat menyebabkan gangguan), jalur akan diubah menjadi /echo/v3.
Deploy ulang aplikasi Frameworks Endpoints Anda.
Memverifikasi deployment baru
Untuk memverifikasi bahwa framework baru menayangkan traffic:
Jika permintaan ditampilkan dengan memiliki jalur yang dimulai dengan /_ah/api, berarti
Endpoints Frameworks versi 2.0 kini menayangkan API Anda. Log
tidak boleh menampilkan permintaan apa pun dengan jalur yang dimulai dengan /_ah/spi. Permintaan ini
menunjukkan bahwa proxy Endpoints versi 1.0
masih menayangkan permintaan.
Menambahkan pengelolaan API
Endpoints Frameworks versi 2.0 menambahkan fitur pengelolaan API,
termasuk:
Bagian ini menjelaskan perilaku tidak stabil yang umum terjadi saat bermigrasi ke Endpoints Frameworks versi 2.0 dan solusi yang disarankan.
API menampilkan error 404, tetapi Penjelajah API masih mencantumkan API dengan benar
Anda harus menghapus konfigurasi Endpoint versi 1.0 lama saat bermigrasi ke Endpoints Frameworks versi 2.0. Jika konfigurasi lama masih ada dalam konfigurasi aplikasi, layanan Endpoints akan terus memperlakukan aplikasi sebagai aplikasi versi 1.0. Anda mungkin melihat permintaan dalam log App Engine yang dikirim ke /_ah/spi, yang mengakibatkan error HTTP 404 dikirim ke klien.
Hapus baris berikut dari file app.yaml jika ada:
handlers:-url:/_ah/spi/.*script:...
Pastikan bagian handlers dalam file app.yaml Anda memiliki jalur
yang benar:
handlers:# The endpoints handler must be mapped to /_ah/api.-url:/_ah/api/.*script:...
Pesan error: ImportError: cannot import name locked_file
Hal ini terjadi jika dependensi Anda berisi versi library oauth2client
yang tidak kompatibel dengan App Engine. Lihat
masalah umum.
[[["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-04 UTC."],[[["\u003cp\u003eEndpoints Frameworks version 2.0 is a migration from the older Endpoints version 1.0, requiring a library change and application configuration update, without needing code alterations.\u003c/p\u003e\n"],["\u003cp\u003eMigrating to Endpoints Frameworks version 2.0 offers benefits such as reduced request latency, improved App Engine integration, and new API management capabilities, while maintaining backward compatibility with existing client interfaces.\u003c/p\u003e\n"],["\u003cp\u003eThe migration process involves creating a \u003ccode\u003e/lib\u003c/code\u003e subfolder, installing the \u003ccode\u003egoogle-endpoints\u003c/code\u003e library, modifying the \u003ccode\u003eapp.yaml\u003c/code\u003e file to remove old Endpoints entries and include new library dependencies, and updating the \u003ccode\u003eurl\u003c/code\u003e directive to \u003ccode\u003e/_ah/api/.*\u003c/code\u003e.\u003c/p\u003e\n"],["\u003cp\u003eEndpoints Frameworks version 2.0 supports various features like JSON-REST protocol, Discovery service, and OAuth2/OpenID Connect authentication, but excludes features like JSON-RPC protocol and automatic ETags.\u003c/p\u003e\n"],["\u003cp\u003eVerifying a successful migration to Endpoints Frameworks version 2.0 involves checking the Cloud Logging for requests with paths beginning with \u003ccode\u003e/_ah/api\u003c/code\u003e, confirming that no requests start with \u003ccode\u003e/_ah/spi\u003c/code\u003e.\u003c/p\u003e\n"]]],[],null,["# Migrating to Cloud Endpoints Frameworks version 2.0\n\nCloud Endpoints Frameworks was formerly called Endpoints. To\ndistinguish between the two versions, this page refers to the new version as\nEndpoints Frameworks version 2.0, and the older version as\nEndpoints version 1.0. This page describes how to migrate an\nCloud Endpoints version 1.0 application to\n[Endpoints Frameworks version 2.0](/endpoints/docs/frameworks/python).\nThe migration consists of a library change and an application configuration\nchange, but you don't have to make any changes to your code.\n\nBenefits\n--------\n\nEndpoints version 2.0 brings a number of benefits, including:\n\n- Reduced request latency.\n- Better integration with App Engine features, such as custom domains.\n- New API management features.\n\nEndpoints Frameworks version 2.0 doesn't affect the interfaces to your\nAPI. Existing clients continue to work after migration without any client-side\ncode changes.\n\nFeature overview\n----------------\n\nThe following features are backward compatible with Endpoints\nversion 1.0:\n\n- JSON-REST protocol, which is used by all Google client libraries\n- Discovery service\n- All existing authentication features (OAuth2/OpenID Connect)\n- Client library support for generated clients\n- CORS (for JavaScript callers not using Google JavaScript client library)\n- API Explorer\n\nTraffic splitting is unavailable.\n\nCurrently excluded features\n---------------------------\n\nThe following features are unavailable. If you require any of these,\nplease submit a\n[feature request](https://github.com/cloudendpoints/endpoints-python/issues).\n\n- JSON-RPC protocol, which is required for legacy iOS clients. To create iOS clients for your Endpoints Frameworks version 2.0 API, we recommend that you use [Google APIs Objective-C client library for REST APIs](https://github.com/google/google-api-objectivec-client-for-rest/wiki).\n- Automatic ETags\n- Automatic `kind` fields\n- IDE integration\n- `fields` partial responses\n- Automatic PATCH API method creation\n\nMigrating from Endpoints version 1.0\n------------------------------------\n\n| **Important:** You must download the linked packages and import them into your application. You must remove the old dependencies.\n\nTo migrate from version 1.0:\n\n1. Create a subfolder named `/lib` in your application's main directory.\n\n2. Install the library from your application's main directory:\n\n pip install -t lib google-endpoints --ignore-installed\n\n3. Remove the `- name: endpoints` and `version 1.0` entries from your\n application's `app.yaml` file under the `libraries` section. For example:\n\n libraries:\n - name: endpoints #Remove\n version: 1.0 #Remove\n\n4. In the `libraries` section in the `app.yaml` file, add the following:\n\n libraries:\n - name: pycrypto\n version: 2.6\n - name: ssl\n version: 2.7.11\n\n Endpoints Frameworks requires these versions of the `pycrypto` and\n `ssl` libraries.\n5. In the `handlers` section in the `app.yaml` file, change the `url` directive\n from `- url: /_ah/spi/.*` to `- url: /_ah/api/.*`.\n\n6. In the root directory of your application, create or modify a file named\n `appengine_config.py` to include the following:\n\n from google.appengine.ext import vendor\n\n vendor.add('lib')\n\n7. Check your API version string. Your version string, specified in the\n `@endpoints.api(version='v1', ...)` decorator, appears in your API's path.\n If you specify a version string compatible with the\n [SemVer standard](https://semver.org/spec/v2.0.0.html),\n only the major version number appears in your API's path when you deploy\n your API. For example, an API called `echo` with version `2.1.0` would\n have a path such as `/echo/v2`. If you update the `echo` API to version\n `2.2.0` and deploy a backwards-compatible change, the path remains `/echo/v2`.\n This allows you to update the API version number when you make a\n backwards-compatible change without breaking existing paths for your clients.\n But if you update the `echo` API to version `3.0.0` (because you are\n deploying a breaking change), the path is changed to `/echo/v3`.\n\n8. Redeploy your Endpoints Frameworks application.\n\n | **Note** : When migrating, you must deploy to a new App Engine version. This is done automatically if you don't specify a version. See [Known Issues](/endpoints/docs/frameworks/known-issues#endpoints_frameworks_migration).\n\n \u003cbr /\u003e\n\n### Verifying a new deployment\n\nTo verify that the new framework is serving traffic:\n\n1. Send some requests to the new deployment.\n2. Visit the Cloud Logging page for your project. \n\n [Go to the Logs Explorer page](https://console.cloud.google.com/logs/query)\n3. If requests are shown with having paths beginning with `/_ah/api`, then Endpoints Frameworks version 2.0 is now serving your API. The logs shouldn't show any requests with paths beginning with `/_ah/spi`. These requests indicate that the Endpoints version 1.0 proxy is still serving requests.\n\nAdding API management\n---------------------\n\nEndpoints Frameworks version 2.0 adds API management features,\nincluding:\n\n- API key management\n- API sharing\n- User authentication\n- API metrics\n- API logs\n\nTo get started, go to the\n[Getting started with Endpoints Frameworks for Python](/endpoints/docs/frameworks/python)\npage.\n\nTroubleshooting\n---------------\n\nThis section describes common erratic behaviors when migrating to\nEndpoints Frameworks version 2.0 and suggested solutions.\n\n### API returns `404` errors, but API Explorer still lists APIs correctly\n\nYou are required to remove the old version 1.0 Endpoints\nconfiguration when migrating to Endpoints Frameworks version 2.0. If\nthe old configuration is still present in the application's configuration, the\nEndpoints service continues to treat the app as a version 1.0\napp. You might see requests in your App Engine logs sent to `/_ah/spi`,\nwhich result in `HTTP 404` errors sent to the client.\n\n1. Remove the following lines, from the `app.yaml` file if they are present:\n\n handlers:\n - url: /_ah/spi/.*\n script: ...\n\n2. Make sure the `handlers` section in your `app.yaml` file has the correct\n path:\n\n handlers:\n # The endpoints handler must be mapped to /_ah/api.\n - url: /_ah/api/.*\n script: ...\n\n### Error message: `ImportError: cannot import name locked_file`\n\nThis happens if your dependencies contain a version of the `oauth2client`\nlibrary that is incompatible with App Engine. See the\n[known issue](/endpoints/docs/frameworks/known-issues#error_message_importerror_cannot_import_name_locked_file)."]]
