Memigrasikan dan Memisahkan Traffic dengan Admin API

ID region

REGION_ID adalah kode singkat yang ditetapkan Google berdasarkan region yang Anda pilih saat membuat aplikasi. Kode ini tidak sesuai dengan negara atau provinsi, meskipun beberapa ID region mungkin tampak mirip dengan kode negara dan provinsi yang umum digunakan. Untuk aplikasi yang dibuat setelah Februari 2020, REGION_ID.r disertakan dalam URL App Engine. Untuk aplikasi lama yang dibuat sebelum tanggal tersebut, ID region bersifat opsional dalam URL.

Pelajari ID region lebih lanjut.

Kelola jumlah traffic yang diterima oleh versi aplikasi Anda dengan memigrasi atau membagi traffic.

Migrasi traffic akan mengalihkan pemilihan rute permintaan dengan lancar, yang secara bertahap memindahkan traffic dari versi yang saat ini menerima traffic ke satu atau beberapa versi yang Anda tentukan.

Pembagian traffic mendistribusikan persentase traffic ke versi aplikasi Anda. Anda dapat memisahkan traffic untuk memindahkan 100% traffic ke satu versi atau merutekan persentase traffic ke beberapa versi. Dengan membagi traffic ke dua versi atau lebih, Anda dapat melakukan pengujian A/B antar-versi dan dapat mengontrol kecepatan saat meluncurkan fitur.

Ingat: Pemisahan traffic diterapkan ke URL yang tidak menarget versi secara eksplisit. Misalnya, URL berikut membagi traffic karena menarget semua versi yang tersedia dalam layanan yang ditentukan:

[MY_PROJECT_ID].[REGION_ID].r.appspot.com - Mendistribusikan traffic ke versi layanan default.
[MY_SERVICE]-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot.com - Mendistribusikan traffic ke versi layanan MY_SERVICE.

REGION_ID adalah kode singkat yang Google tetapkan berdasarkan region yang Anda pilih saat membuat aplikasi. Kode ini tidak sesuai dengan negara atau provinsi, meskipun beberapa ID region mungkin tampak mirip dengan kode provinsi dan negara yang umum digunakan. Untuk aplikasi yang dibuat setelah Februari 2020, REGION_ID.r disertakan dalam URL App Engine. Untuk aplikasi lama yang dibuat sebelum tanggal ini, ID region bersifat opsional dalam URL.

Untuk informasi selengkapnya, lihat Cara Permintaan Diarahkan.

Untuk melakukan migrasi dan pemisahan traffic secara manual dari Konsol Google Cloud, lihat Memigrasikan Traffic dan Memisahkan Traffic.

Sebelum memulai

Migrasi traffic dengan Admin API berperilaku berbeda dengan konsol Google Cloud. Untuk memigrasikan traffic dengan Admin API, Anda harus dapat mengizinkan permintaan HTTP dan versi Anda harus memenuhi persyaratan migrasi traffic:

Persyaratan migrasi traffic (migrateTraffic=true):

Akun pengguna Anda harus menyertakan hak istimewa yang diperlukan sebelum Anda dapat mengonfigurasi traffic.
Migrasi traffic bertahap tidak didukung di lingkungan fleksibel App Engine.
Untuk melakukan migrasi traffic secara bertahap, versi target harus ditempatkan di dalam instance yang dikonfigurasi untuk:
- Warmup request
- Penskalaan otomatis
  
  Untuk informasi konfigurasi, lihat Referensi app.yaml.

Memigrasikan atau memisahkan traffic

Untuk memigrasikan atau membagi traffic antar-versi aplikasi Anda:

Mengizinkan permintaan HTTP Anda, misalnya mendapatkan token akses.

Mengizinkan akses ke Admin API dapat dilakukan dengan alur OAuth yang berbeda, bergantung pada kebutuhan aplikasi API Anda. Untuk informasi selengkapnya, lihat Mengakses API.

Tips: Jika ingin menggunakan token akses, Anda bisa segera mendapatkannya dari OAuth 2.0 Playground.
Gunakan metode patch dari koleksiapps.services untuk memperbarui konfigurasi versi Anda guna memigrasikan traffic atau mengonfigurasi pemisahan traffic. Contoh permintaan PATCH HTTP berikut telah sengaja digabungkan agar mudah dibaca:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/
  ?updateMask=split {
    "split": {
      "shardBy": "[MY_SHARDBY_METHOD]",
      "allocations": { "[MY_APP_VERSION]": [MY_TRAFFIC_PERCENT] }
    }
  }
```
Kolom dan parameter permintaan HTTP:
- updateMask: Menentukan kolom mana dalam konfigurasi yang akan diperbarui.
- migrateTraffic=true (opsional): Menentukan untuk memigrasikan traffic secara bertahap.
  Penting: Versi yang traffic yang ingin Anda migrasikan harus memenuhi persyaratan migrasi traffic.
- split: Menentukan konfigurasi untuk traffic ke versi Anda.
  - shardBy (opsional): Menentukan metode yang digunakan untuk memisahkan traffic. Diperlukan untuk migrasi traffic bertahap (migrateTraffic=true). Nilai yang valid adalah COOKIE atau IP.
  - allocations: Menentukan satu atau beberapa versi dan persentase traffic yang didistribusikan ke setiap versi. Versi dan persentase traffic ditentukan sebagai pasangan key:value. Persentase traffic ditentukan sebagai pecahan desimal dan harus berjumlah 1. Contoh: "allocations": { "v1": 0.8, "v2": 0.2 }
Lihat koleksiapps.services untuk mengetahui detail dan daftar lengkap parameter serta kolom.

Contoh permintaan HTTP:
- Memindahkan semua traffic ke versi:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "v1": 1 } } }
```
- Migrasikan semua traffic ke v2:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": 1 } } }
```
- Bagi 80% traffic ke versi v1 dan 20% ke v2:
```
PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { "split": { "shardBy": "IP", "allocations": { "v1": 0.8, "v2": 0.2 } } }
```

Contoh: Memindahkan traffic ke versi lain

Contoh ini menunjukkan cara memindahkan semua traffic ke versi baru yang baru saja Anda deploy. Misalnya, server menampilkan error sehingga Anda telah memperbaiki bug, men-deploy versi v2 baru, dan sekarang ingin mengalihkan semua traffic.

Untuk memindahkan semua traffic dari v1 ke v2:

Pastikan 100% traffic saat ini dikirim ke versi v1 dengan metode GET dari koleksi apps.services.

Contoh permintaan GET HTTP:

GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

Contoh perintah cURL:

 curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

Contoh respons:

{
  "name": "apps/[MY_PROJECT_ID]/services/default",
  "id": "default",
  "split": {
    "allocations": {
      "v1": 1
    }
  }
}

Perbarui konfigurasi pemisahan traffic sehingga semua traffic dipindahkan ke versi baru menggunakan metode PATCH dari koleksi apps.services.

Dalam permintaan PATCH HTTP, Anda harus menentukan layanan dalam aplikasi Anda tempat kedua versi berjalan, misalnya default. Anda juga harus menyertakan kolom updateMask dengan nilai split untuk menentukan bahwa Anda memperbarui konfigurasi pemisahan traffic.

Contoh permintaan PATCH HTTP:

PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "v2": "1" } } }

Contoh perintah cURL:

curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'allocations': { 'v2': '1' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split

Contoh respons:

{
  "name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420",
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "insertTime": "2015-05-29T17:25:30.413Z",
    "method": "com.google.appengine.v1.Services.UpdateService",
    "target": "apps/[MY_PROJECT_ID]/services/default",
    "user": "me@example.com"
  }
}

PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split&migrateTraffic=true {"split": { "shardBy": "IP", "allocations": { "v2": "1" } } }

Pastikan pembaruan konfigurasi telah selesai:
1. Lihat status operasi update dengan permintaan GET HTTP:
  
  Untuk melihat status operasi yang melakukan update, gunakan metode GET dari koleksi apps.operations beserta operasi name yang ditampilkan dalam respons HTTP dari langkah sebelumnya:
  
  Contoh permintaan GET HTTP:
```
GET https://appengine.googleapis.com/v1/[OPERATION_NAME]
```
  Dengan [OPERATION_NAME] adalah nilai kolom name dalam respons permintaan PATCH HTTP yang Anda kirim pada langkah sebelumnya.
  
  Jika respons HTTP dari langkah sebelumnya mencakup:
```
"name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420"
```
  Maka, Anda mengirim permintaan HTTP berikut untuk melihat status operasinya:
```
GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
```
  Contoh perintah cURL:
```
curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420
```
2. Setelah operasi selesai, Anda dapat melihat detail layanan dengan versi GET HTTP lainnya:
  
  Contoh permintaan GET HTTP:
```
GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
```
  Contoh perintah cURL:
```
curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default
```
Opsional: Anda kini dapat menghapus versi v1 yang rusak dari aplikasi App Engine dengan permintaan DELETE HTTP.

Contoh permintaan DELETE HTTP:
```
DELETE https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/v1
```
Contoh perintah cURL:
```
curl -X DELETE -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/v1
```
Tips: Anda dapat menjalankan dua permintaan GET HTTP untuk memverifikasi bahwa operasi berhasil, satu untuk memverifikasi bahwa operasi penghapusan selesai, dan satu untuk memverifikasi bahwa operasi penghapusan bahwa versi tersebut telah dihapus.

Contoh: Memisahkan traffic antar-versi

Contoh ini menunjukkan cara mengonfigurasi pemisahan traffic di beberapa versi aplikasi Anda. Misalnya, Anda baru saja membuat versi v2 dan v3 yang masing-masing menyertakan fitur baru, tetapi Anda ingin meluncurkan fitur tersebut secara perlahan sehingga masing-masing hanya menerima 20% traffic.

Setelah men-deploy versi App Engine v2 dan v3, Anda bisa menggunakan permintaan PATCH HTTP untuk mengkonfigurasi tiga versi sehingga traffic dibagi 60% untuk v1 dan 20% masing-masing untuk v2 dan v3 .

Contoh permintaan PATCH HTTP:

PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { "split": { "shardBy": "IP", "allocations": { "v1": "0.6", "v2": "0.2", "v3": "0.2" } } }

Contoh perintah cURL:

curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'shardBy': 'IP', 'allocations': { 'v1': '0.6', 'v2': '0.2', 'v3': '0.2' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split

Setelah memverifikasi bahwa operasi telah selesai, Anda dapat mengirim permintaan GET HTTP untuk memverifikasi bahwa traffic telah dibagi di seluruh versi, misalnya:

Contoh permintaan PATCH HTTP:

GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

Contoh perintah cURL:

curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

Contoh respons:

{
  "name": "apps/[MY_PROJECT_ID]/services/default",
  "id": "default",
  "split": {
    "allocations": {
      "v1": 0.6,
      "v2": 0.2,
      "v3": 0.2
    }
  }
}