Mulai Menggunakan 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.

Oke

Panduan ini dirancang untuk membantu Anda mempelajari cara menggunakan App Engine Admin API untuk men-deploy contoh aplikasi Python ke App Engine. Anda dapat menggunakan keseluruhan proses untuk mendapatkan insight tentang cara membuat kode yang mengelola dan men-deploy aplikasi Anda secara terprogram.

Dalam panduan ini, contoh yang digunakan adalah aplikasi Halo Dunia sederhana yang menampilkan teks "Hello, World!" (Halo Dunia!) dan tersedia di GitHub. Untuk otorisasi dengan konsol Google Cloud, client ID OAuth dan browser web digunakan. Untuk menunjukkan setiap langkah proses, perintah cURL disediakan sehingga Anda dapat mengirim permintaan HTTP dari terminal Anda.

Tips: Untuk menguji coba dan melihat apa yang dapat dilakukan API tanpa perlu menulis kode apa pun atau menyiapkan project dan kredensial, buka APIs Explorer ,

Tujuan

• Aktifkan API di project konsol Google Cloud Anda dan buat kredensial client ID OAuth.
• Mendapatkan token akses untuk mengautentikasi dengan App Engine.
• Gunakan Admin API untuk men-deploy aplikasi contoh ke App Engine.
• Opsional: Konfigurasikan traffic ke versi tempat Anda men-deploy aplikasi contoh.

Catatan: Biasanya, Anda harus membuat bucket Google Cloud Storage terlebih dahulu, lalu mengupload salinan aplikasi sebelum dapat men-deploy-nya ke App Engine dengan Admin API. Namun, panduan ini menggunakan resource aplikasi Halo Dunia yang telah diupload ke bucket Cloud Storage publik. Untuk mengetahui informasi selengkapnya tentang proses deployment, lihat Men-deploy Versi Aplikasi Anda.

Sebelum memulai

• Anda harus memiliki atau membuat Akun Google.
• Download dan instal Google Cloud CLI, lalu inisialisasi gcloud CLI:
  Download SDK

Penting: Langkah-langkah dan semua contoh yang terkait mengacu pada contoh project Google Cloud [MY_PROJECT_ID]. Untuk menjalankan perintah pada project, Anda harus mengganti semua instance [MY_PROJECT_ID] dengan project ID Anda.
Untuk informasi tentang cara membuat project Google Cloud, lihat petunjuk untuk bahasa Anda: lingkungan standar atau lingkungan fleksibel.

Tips: Jika Anda ingin menjalankan aplikasi Halo Dunia secara manual secara lokal, lihat Panduan memulai untuk Python App Engine Standard Lingkungan.

Mengonfigurasi project Google Cloud Anda

Aktifkan App Engine Admin API dan Cloud Storage API di project Google Cloud Anda, lalu konfigurasikan kredensial:

1. Aktifkan API di konsol Google Cloud:

   Aktifkan API

2. Di wizard, pilih project yang sudah ada dari daftar atau klik Lanjutkan untuk membuat project baru.

3. Klik Lanjutkan untuk membuat kredensial client ID OAuth:

   1. Di layar izin OAuth, tentukan minimal Alamat email Anda dan Nama produk ditampilkan kepada pengguna.
   2. Simpan setelan layar izin, lalu beralihlah ke tab Kredensial dengan mengklik Simpan.
   3. Klik Buat kredensial, lalu client ID OAuth untuk membuat client ID.

   4. Klik Aplikasi web, tentukan nama, lalu gunakan https://www.google.com sebagai URI pengalihan.

      Catatan: URI pengalihan menentukan tujuan pengiriman respons HTTP. URI https://www.google.com digunakan dalam panduan ini sebagai contoh, tetapi untuk produksi, Anda harus menentukan endpoint autentikasi aplikasi, yang menangani respons dari server OAuth 2.0.

   5. Klik Buat untuk menyimpan kredensial.

   6. Catat client ID yang ditampilkan karena akan digunakan dalam pengisian token akses yang diminta pada langkah berikutnya.

Untuk mengetahui informasi selengkapnya tentang cara membuat kredensial untuk Admin API, lihat Mengakses API.

Membuat file konfigurasi

Buat file konfigurasi yang menentukan deployment aplikasi Halo Dunia. Dalam file bernama app.json, Anda menentukan bucket Cloud Storage aplikasi Hello World di kolom sourceUrl dan informasi konfigurasi untuk versi, termasuk ID versi di dalam Kolom id.

{
  "deployment": {
    "files": {
      "main.py": {
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
      },
    }
  },
  "handlers": [
    {
      "script": {
        "scriptPath": "main.app"
      },
      "urlRegex": "/.*"
    }
  ],
  "runtime": "python27",
  "threadsafe": true,
  "id": "appengine-helloworld",
  "inboundServices": [
    "INBOUND_SERVICE_WARMUP"
  ]
}

Contoh, root/python-docs-samples/appengine/standard/hello_world/app.json

Catatan: Biasanya Anda menggunakan alat convert_yaml.py untuk membuat file konfigurasi berformat JSON. Anda harus mengonversi file app.yaml aplikasi, lalu menentukan semua resource aplikasi yang ingin di-deploy dari bucket Cloud Storage. Untuk mengetahui informasi selengkapnya tentang konversi file app.yaml, lihat Men-deploy Versi ke Aplikasi Anda.

Mengizinkan permintaan HTTP

Lakukan autentikasi dengan App Engine agar Anda dapat mengirim permintaan HTTP dengan Admin API.

Gunakan salah satu opsi berikut untuk membantu Anda memulai dengan cepat. Opsi HTTPS dan gcloud memberi Anda langkah-langkah manual tetapi sederhana untuk mendapatkan token akses untuk tujuan mencoba Admin API.

HTTPS

Untuk menyimulasikan alur OAuth 2.0 sisi klien, tambahkan kredensial client ID OAuth Anda ke URI, lalu kirim permintaan HTTPS melalui browser web:

1. Di browser web, minta token akses menggunakan client ID dari kredensial API Anda. Contoh berikut menggunakan client_id=[MY_CLIENT_ID] dan redirect_uri=https://www.google.com, dengan [MY_CLIENT_ID] adalah client ID dari kredensial yang Anda buat sebelumnya:

   https://accounts.google.com/o/oauth2/v2/auth?response_type=token&client_id=[MY_CLIENT_ID]&scope=https://www.googleapis.com/auth/cloud-platform&redirect_uri=https://www.google.com
   

2. Ambil token akses dari respons permintaan.

   Kolom alamat di browser web Anda harus berisi URI pengalihan yang Anda tentukan di kredensial bersama dengan token akses yang ditambahkan ke URI, misalnya:

   https://www.google.com/#access_token=[MY_ACCESS_TOKEN]&token_type=Bearer&expires_in=3600
   

   Sekarang, Anda dapat menggunakan token akses [MY_ACCESS_TOKEN] yang disediakan di kolom access_token untuk mengirim permintaan HTTP ke project Google Cloud Anda.

gcloud

Untuk mengambil token akses saja, jalankan perintah gcloud berikut:

1. Tetapkan Kredensial Default Aplikasi (ADC) yang ingin Anda gunakan untuk meminta token akses:

   gcloud auth application-default login
   

2. Minta token akses:

   gcloud auth application-default print-access-token
   

Untuk mengetahui detail tentang perintah ini, lihat gcloud auth application-default.

Ingat: Masa berlaku token akses Anda berakhir sekitar 60 menit setelah dikeluarkan.

Opsi di atas tidak ditujukan untuk digunakan dalam implementasi terprogram, tetapi informasi tentang cara menerapkan alur otorisasi OAuth 2.0 tersedia di Mengakses Admin API.

Men-deploy aplikasi Halo Dunia

Anda menggunakan permintaan HTTP untuk men-deploy aplikasi Hello World dengan Admin API:

1. Kirim permintaan POST HTTP menggunakan Admin API untuk men-deploy versi aplikasi Halo Dunia ke aplikasi App Engine Anda, misalnya:

   POST https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions app.json
   

   Contoh perintah cURL:

   Jalankan perintah dari direktori tempat Anda membuat file konfigurasi app.json, misalnya:

   cd root/python-docs-samples/appengine/standard/hello_world/
   
   curl -X POST -T "app.json" -H "Content-Type: application/json" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions
   

   Dengan keterangan:

   • [MY_ACCESS_TOKEN] adalah token akses yang Anda dapatkan untuk mengizinkan permintaan HTTP Anda.
   • [MY_PROJECT_ID] adalah ID project tempat Anda ingin men-deploy versi.

   Contoh respons:

   {
     "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
     "metadata": {
       "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
       "insertTime": "2016-07-29T17:12:44.679Z",
       "method": "google.appengine.v1.Versions.CreateVersion",
       "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
       "user": "[e-mail]"
     }
   }
   

   Dengan [MY_PROJECT_ID] sebagai project ID Google Cloud Anda.

2. Pastikan versi aplikasi Halo Dunia berhasil di-deploy ke aplikasi App Engine Anda:

   1. Lihat status operasi deployment yang sebenarnya menggunakan nama operasi yang ditampilkan di langkah sebelumnya sebagai name bidang dalam metode HTTP GET , misalnya:

      GET https://appengine.googleapis.com/v1/[OPERATION_NAME]
      

      Contoh perintah cURL:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/[OPERATION_NAME]
      

      Dengan keterangan:

      • [OPERATION_NAME] adalah nilai kolom name yang ditampilkan di langkah sebelumnya saat Anda men-deploy aplikasi, misalnya apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85.
      • [MY_ACCESS_TOKEN] adalah token akses yang Anda dapatkan untuk mengizinkan permintaan HTTP Anda.
      • [MY_PROJECT_ID] adalah ID project tempat Anda ingin men-deploy versi.

      Contoh respons:

      {
        "done": true,
        "metadata": {
          "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
          "endTime": "2016-07-29T17:13:20.424Z",
          "insertTime": "2016-07-29T17:12:44.679Z",
          "method": "google.appengine.v1.Versions.CreateVersion",
          "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
          "user": "[e-mail]"
        },
        "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
        "response": {
          "@type": "type.googleapis.com/google.appengine.v1.Version",
          "creationTime": "2016-07-29T17:12:46.000Z",
          "deployer": "[e-mail]",
          "id": "appengine-helloworld",
          "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
          "runtime": "python27",
          "servingStatus": "SERVING",
          "threadsafe": true,
        }
      }
      

      Dengan [MY_PROJECT_ID] sebagai project ID Google Cloud Anda.

   2. Pastikan versi aplikasi Halo Dunia telah dibuat di aplikasi App Engine Anda menggunakan permintaan GET HTTP untuk melihat detail versi, misalnya:

      GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL
      

      Contoh perintah cURL:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL
      

      Dengan keterangan:

      • [MY_ACCESS_TOKEN] adalah token akses yang Anda dapatkan untuk mengizinkan permintaan HTTP Anda.
      • [MY_PROJECT_ID] adalah ID project tempat Anda ingin men-deploy versi.

      Contoh respons:

      {
        "creationTime": "2016-07-29T17:12:46.000Z",
        "deployer": "[e-mail]",
        "deployment": {
          "files": {
            "main.py": {
              "sha1Sum": "13f7ea1e24f7cd2de5c66660525f2b509da37c14",
              "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
            }
          }
        },
        "handlers": [
          {
            "authFailAction": "AUTH_FAIL_ACTION_REDIRECT",
            "login": "LOGIN_OPTIONAL",
            "script": {
              "scriptPath": "main.app",
            },
            "securityLevel": "SECURE_OPTIONAL",
            "urlRegex": "/.*"
          }
        ]
        "id": "appengine-helloworld",
        "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
        "runtime": "python27",
        "servingStatus": "SERVING",
        "threadsafe": true,
        "versionUrl": "https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot"
      }
      

      Dengan [MY_PROJECT_ID] sebagai project ID Google Cloud Anda.

3. Tampilkan aplikasi Halo Dunia di browser web Anda dengan mengunjungi URL yang ditentukan dalam kolom versionUrl respons HTTP dari langkah sebelumnya, misalnya:

   https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot.com
   

   Dengan [MY_PROJECT_ID] sebagai project ID Google Cloud Anda.

   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.

4. Mengonfigurasi traffic ke aplikasi Halo Dunia.

   Secara default, versi awal yang Anda deploy ke aplikasi App Engine baru secara otomatis menerima 100% traffic dan versi berikutnya tidak akan menerima traffic.

   1. Untuk melihat apakah versi Anda dikonfigurasi untuk menerima traffic, kirim permintaan GET HTTP, misalnya:

      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
      

      Dengan keterangan:

      • [MY_ACCESS_TOKEN] adalah token akses yang Anda dapatkan untuk mengizinkan permintaan HTTP Anda.
      • [MY_PROJECT_ID] adalah ID project tempat Anda ingin men-deploy versi.

      Contoh respons:

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

      Dengan [MY_PROJECT_ID] sebagai project ID Google Cloud Anda.

   2. Untuk memindahkan semua traffic ke suatu versi, kirim permintaan PATCH HTTP, misalnya:

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

      Contoh perintah cURL:

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

      Dengan keterangan:

      • [MY_ACCESS_TOKEN] adalah token akses yang Anda dapatkan untuk mengizinkan permintaan HTTP Anda.
      • [MY_PROJECT_ID] adalah ID project tempat Anda ingin men-deploy versi.

      Contoh respons:

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

      Dengan [MY_PROJECT_ID] sebagai project ID Google Cloud Anda.

Pembelajaran yang diperluas

Jika memiliki lebih dari satu versi aplikasi, Anda dapat melakukan langkah-langkah berikut untuk membagi traffic antar-versi tersebut:

1. Untuk men-deploy aplikasi Halo Dunia versi kedua ke aplikasi App Engine yang sama:

   1. Dalam file konfigurasi app.json aplikasi Halo Dunia yang sudah ada yang Anda buat sebelumnya, perbarui kolom id untuk menentukan versi lain. Misalnya, tambahkan -2:

      "id": "appengine-helloworld-2"
      

   2. Lakukan semua langkah yang sama lagi untuk men-deploy versi appengine-helloworld-2, misalnya:

      1. Lakukan autentikasi dengan project Anda.
      2. Deploy versi appengine-helloworld-2 baru.
      3. Verifikasi bahwa versi appengine-helloworld-2 berhasil di-deploy.
      4. Lihat aplikasi yang berjalan di browser web Anda.

2. Ikuti petunjuk untuk memisahkan traffic dalam Memigrasikan dan Memisahkan Traffic, misalnya Anda mengirim permintaan PATCH HTTP:

   PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }
   

   Contoh perintah cURL:

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

   Dengan keterangan:

   • [MY_ACCESS_TOKEN] adalah token akses yang Anda dapatkan untuk mengizinkan permintaan HTTP Anda.
   • [MY_PROJECT_ID] adalah ID project tempat Anda ingin men-deploy versi.

Langkah selanjutnya

• Buat, konfigurasi, lalu siapkan kredensial untuk aplikasi Anda: Mengakses API