Admin API 入門指南

本指南旨在協助您瞭解如何使用 Google App Engine Admin API 將 Python 應用程式範例部署至 App Engine。您可以透過整體程序深入瞭解如何建立程式碼來透過程式管理及部署應用程式。

在本指南中使用的範例是 Hello World 應用程式範例,範例中顯示了「Hello, World!」,並且可從 GitHub 取得範例程式碼。如需 GCP 主控台的授權,我們會使用 OAuth 用戶端 ID 與網路瀏覽器。為了示範此程序的個別步驟,我們提供了 cURL 指令,讓您能夠從終端機傳送 HTTP 要求。

目標

  • 在您的 GCP 主控台專案中啟用 API 並建立 OAuth 用戶端 ID 憑證。
  • 取得向 App Engine 驗證的存取憑證。
  • 使用 Admin API 將應用程式範例部署至 App Engine。
  • 選用:設定您部署應用程式範例所在版本的流量。

事前準備

  • 您必須擁有或建立 Google 帳戶
  • 下載並安裝 Google Cloud SDK,然後初始化 gcloud 工具:
    下載 SDK

提示:如要在本機手動執行 Hello World 應用程式,請參閱 Python App Engine 標準環境的快速入門導覽課程

設定 GCP 專案

在 GCP 專案中啟用「Google App Engine Admin API」與「Cloud Storage」API,然後設定憑證:

  1. 在 GCP 主控台中啟用 API:

    啟用 API

  2. 在精靈中,從清單選取現有專案或按一下 [Continue] (繼續) 以建立新專案。

  3. 按一下 [Continue] (繼續) 以建立 OAuth 用戶端 ID 憑證:

    1. 在「OAuth consent screen」(OAuth 同意畫面) 中至少指定您的「Email address」(電子郵件地址) 與「Product name shown to users」(向使用者顯示的產品名稱)。
    2. 儲存同意畫面設定,然後按一下 [Save] (儲存) 切換至「Credentials」(憑證) 分頁。
    3. 按一下 [Create credentials] (建立憑證),然後點選 [OAuth client ID] (OAuth 用戶端 ID) 以建立用戶端 ID。
    4. 按一下 [Web application] (網路應用程式),指定名稱,然後使用 https://www.google.com 做為重新導向 URI。

    5. 按一下 [Create] (建立) 來儲存憑證。

    6. 請記下顯示的用戶端 ID,因為該用戶端 ID 將在後續步驟中用來要求存取憑證。

如要進一步瞭解如何建立 Admin API 的憑證,請參閱存取 API 一文。

建立設定檔

建立定義 Hello World 應用程式部署作業的設定檔。在名為 app.json 的檔案中,您在 sourceURL 欄位中定義了 Hello World 應用程式的 Cloud Storage 值區,並定義了版本的設定資訊,包括 id 欄位中的版本 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"
  ]
}

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

授權 HTTP 要求

向 App Engine 驗證可讓您使用 Admin API 傳送 HTTP 要求。

請使用下列任一選項來協助您快速開始。HTTPSgcloud 選項都為您提供以手動方式完成但很簡單的步驟來取得用於試用 Admin API 的存取憑證。

HTTPS

如要模擬用戶端 OAuth 2.0 流程,請將您的 OAuth 用戶端 ID 憑證新增至 URI,然後透過網路瀏覽器傳送 HTTPS 要求:

  1. 在網路瀏覽器中,使用 API 憑證的用戶端 ID 要求存取憑證。以下範例使用 client_id=[MY_CLIENT_ID]redirect_uri=https://www.google.com,其中 [MY_CLIENT_ID] 是您稍早時建立的憑證的用戶端 ID:

    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. 從要求回應擷取存取憑證。

    網路瀏覽器的位址欄位中應包含您在憑證中指定的重新導向 URI 以及附加至 URI 的存取憑證,例如:

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

    現在,您可以使用 access_token 欄位提供的存取憑證 [MY_ACCESS_TOKEN] 來將 HTTP 要求傳送至您的 GCP 專案。

gcloud

如果只是要擷取存取憑證,請執行下列 gcloud 指令:

  1. 設定您要用於要求存取憑證的應用程式預設憑證 (ADC)

    gcloud auth application-default login
    
  2. 要求存取憑證:

    gcloud auth application-default print-access-token
    

如要進一步瞭解這些指令,請參閱 gcloud auth application-default

請記住:您的存取憑證會在發出之後約 60 分鐘到期。

以上選項非供用於程式輔助實作,但有關如何實作 OAuth 2.0 授權流程的資訊可在存取 Admin API 一文中找到。

部署 Hello World 應用程式

您可以使用 HTTP 要求來透過 Admin API 部署 Hello World 應用程式:

  1. 使用 Admin API 傳送 HTTP POST 要求以將 Hello World 應用程式的版本部署至 App Engine 應用程式,例如:

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

    cURL 指令範例:

    從您建立 app.json 設定檔所在的目錄中執行指令,例如:

    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
    

    其中:

    • [MY_ACCESS_TOKEN] 是您取得以授權 HTTP 要求的存取憑證。
    • [MY_PROJECT_ID] 是您要部署版本所在專案的 ID。

    回應範例:

    {
      "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": "me@example.com"
      }
    }
    

    其中 [MY_PROJECT_ID] 是您的 GCP 專案 ID。

  2. 驗證 Hello World 應用程式的版本是否已成功部署至 App Engine 應用程式:

    1. 使用在上一步中傳回的作業名稱查看實際部署作業的狀態,如 HTTP GET 方法中的 name 欄位,例如:

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

      cURL 指令範例:

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

      其中:

      • [OPERATION_NAME] 是您在部署應用程式的上一步中傳回的 name 欄位值,例如 apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85
      • [MY_ACCESS_TOKEN] 是您取得以授權 HTTP 要求的存取憑證。
      • [MY_PROJECT_ID] 是您要部署版本所在專案的 ID。

      回應範例:

      {
        "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": "me@example.com"
        },
        "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": "me@example.com",
          "id": "appengine-helloworld",
          "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
          "runtime": "python27",
          "servingStatus": "SERVING",
          "threadsafe": true,
        }
      }
      

      其中 [MY_PROJECT_ID] 是您的 GCP 專案 ID。

    2. 使用 HTTP GET 要求查看版本詳細資料,驗證 Hello World 應用程式的版本是否已在 App Engine 應用程式中建立,例如:

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

      cURL 指令範例:

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

      其中:

      • [MY_ACCESS_TOKEN] 是您取得以授權 HTTP 要求的存取憑證。
      • [MY_PROJECT_ID] 是您要部署版本所在專案的 ID。

      回應範例:

      {
        "creationTime": "2016-07-29T17:12:46.000Z",
        "deployer": "me@example.com",
        "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].appspot.com"
      }
      

      其中 [MY_PROJECT_ID] 是您的 GCP 專案 ID。

  3. 造訪在上一步 HTTP 回應的 versionUrl 欄位中指定的網址,在網路瀏覽器中查看 Hello World 應用程式,例如:

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

    其中 [MY_PROJECT_ID] 是您的 GCP 專案 ID。

  4. 設定 Hello World 應用程式的流量。

    根據預設,您部署至新 App Engine 應用程式的初始版本均會自動接收 100% 的流量,而任何後續版本均會接收零流量。

    1. 如要查看您的版本是否設定為接收流量,您可以傳送 HTTP GET 要求,例如:

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

      cURL 指令範例:

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

      其中:

      • [MY_ACCESS_TOKEN] 是您取得以授權 HTTP 要求的存取憑證。
      • [MY_PROJECT_ID] 是您要部署版本所在專案的 ID。

      回應範例:

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

      其中 [MY_PROJECT_ID] 是您的 GCP 專案 ID。

    2. 如要將所有流量移至版本,您可以傳送 HTTP PATCH 要求,例如:

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

      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
      

      其中:

      • [MY_ACCESS_TOKEN] 是您取得以授權 HTTP 要求的存取憑證。
      • [MY_PROJECT_ID] 是您要部署版本所在專案的 ID。

      回應範例:

      {
        "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": "me@example.com"
        }
      }
      

      其中 [MY_PROJECT_ID] 是您的 GCP 專案 ID。

延伸學習

如果您的應用程式有多個版本,可以執行下列步驟來拆分這些版本的流量:

  1. 如要將 Hello World 應用程式的第二個版本部署至相同的 App Engine 應用程式:

    1. 在您稍早時建立的 Hello World 應用程式的現有 app.json 設定檔中,更新 id 欄位以指定其他版本。例如,附加 -2

      "id": "appengine-helloworld-2"
      
    2. 再次執行所有相同的步驟來部署 appengine-helloworld-2 版本,例如:

      1. 向專案驗證。
      2. 部署新的 appengine-helloworld-2 版本。
      3. 驗證是否已成功部署 appengine-helloworld-2 版本。
      4. 在網路瀏覽器中查看執行中的應用程式。
  2. 依照遷移及拆分流量一文中的拆分流量操作說明執行,例如,您可以傳送 HTTP PATCH 要求:

    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' } } }
    

    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
    

    其中:

    • [MY_ACCESS_TOKEN] 是您取得以授權 HTTP 要求的存取憑證。
    • [MY_PROJECT_ID] 是您要部署版本所在專案的 ID。

後續步驟

  • 為應用程式進行建立、設定,然後設定應用程式的憑證:存取 API
本頁內容對您是否有任何幫助?請提供意見:

傳送您對下列選項的寶貴意見...

這個網頁
App Engine Admin API