步驟 4：建立機構

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

您已建立 Google Cloud 帳戶和專案，並啟用 API。您現在可以建立機構。

修課條件

如要建立機構，您必須符合下列其中一個條件：

• 擁有評估帳戶。評估帳戶的有效期限為 60 天。屆時系統會刪除該機構。
• 擁有付費帳戶

如果以上皆非，您必須先與 Apigee 銷售團隊聯絡，才能繼續操作。

如要建立新的機構並進行佈建，請按照下列步驟操作：

1. 在指令列中取得 gcloud 驗證憑證，如以下範例所示：

   TOKEN=$(gcloud auth print-access-token)

   如要確認權杖是否已填入，請使用 echo，如以下範例所示：

   echo $TOKEN

   權杖應會以編碼字串的形式顯示。

   如需詳細資訊，請參閱 gcloud 指令列工具總覽。

2. 為組織的元素建立下列環境變數。您會在建立 org 的指令中使用這些值。
   • PROJECT_ID (必填)：您要將哪個 Google Cloud 專案繫結至新的混合式機構。這是 Google 在步驟 2：建立 Google Cloud 專案中為您產生的 ID。

     export PROJECT_ID=your_project_id

     

   • ORG_NAME (必填)：您要為啟用混合式功能的機構使用的程式輔助 ID。

     export ORG_NAME=$PROJECT_ID

   • ORG_DISPLAY_NAME(選用)：機構的友善名稱。這個值不必是唯一值，且可以包含空格和特殊字元。例如「My Hybrid Organization」。

     ORG_DISPLAY_NAME="friendly_name"

     變數名稱內容如果包含空格，必須以雙引號括住。例如：「My Organization」

   • ORGANIZATION_DESCRIPTION (選填) 是您想用來提醒機構用途的資訊。例如「我的第一個組織」。

     ORGANIZATION_DESCRIPTION="description_text"

   • ANALYTICS_REGION (必填)：數據分析資料儲存空間的主要區域。

     export ANALYTICS_REGION=analytics_region

     其中 analytics_region 是下列其中一個：

     asia-northeast1	asia-south1	australia-southeast1
     us-central1	us-east1	us-west1
     europe-west2	europe-west1

     請選擇地理位置相近的區域，或是符合貴機構儲存空間需求的區域。

   • RUNTIMETYPE (必填)：Apigee 機構的執行階段類型，其中 HYBRID 是使用者管理的 Apigee Hybrid 執行階段。

     export RUNTIMETYPE=HYBRID

3. 將經過驗證的 POST 要求傳送至 Create organizations API。

   以下範例顯示建立機構的要求結構：

   curl -H "Authorization: Bearer $TOKEN" -X POST -H "content-type:application/json" \
     -d '{
       "name":"'"$ORG_NAME"'",
       "displayName":"'"$ORG_DISPLAY_NAME"'",
       "description":"'"$ORGANIZATION_DESCRIPTION"'",
       "runtimeType":"'"$RUNTIMETYPE"'",
       "analyticsRegion":"'"$ANALYTICS_REGION"'"
     }' \
     "https://apigee.googleapis.com/v1/organizations?parent=projects/$PROJECT_ID"

   建立要求成功後，組織 API 應傳回類似下列的訊息：

   {
     "name": "organizations/org_name/operations/long_running_operation_ID",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
       "operationType": "INSERT",
       "targetResourceName": "organizations/org_name",
       "state": "IN_PROGRESS"
     }
   }

   其中：

   • long_running_operation_ID 是長時間執行的非同步作業 UUID。您可以使用這個 ID 查看機構建立要求的狀態 (請參閱步驟 5)。
   • org_name 是目前正在建立的新機構 ID。

   如回應中的 state 屬性所示，Apigee 已開始建立新機構，因此其狀態為 IN_PROGRESS。這項作業可能需要幾分鐘才能完成。

   如果系統顯示錯誤訊息，請參閱「排解機構建立問題」一文。

4. 將長時間執行作業 ID 儲存至環境變數。這對日後的管理工作很有幫助。

   語法

   export LONG_RUNNING_OPERATION_ID=long_running_operation_ID

   範例

   export LONG_RUNNING_OPERATION_ID=6abc8a72-46de-f9da-bcfe-70d9ab347e4f

5. 您可以檢查長時間執行作業的狀態，該作業的 ID 會在初始建立要求中傳回。方法就是使用 operations API。例如：

   curl -H "Authorization: Bearer $TOKEN" \
     "https://apigee.googleapis.com/v1/organizations/$ORG_NAME/operations/$LONG_RUNNING_OPERATION_ID"

   以下範例顯示對此要求的可能回應：

   IN_PROGRESS

   如果 Apigee 仍在建立機構，Apigee 會傳回 IN_PROGRESS 狀態。例如：

   {
       "name": "organizations/org_name/operations/long_running_operation_ID",
       "metadata": {
         "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
         "operationType": "INSERT",
         "targetResourceName": "organizations/org_name",
         "state": "IN_PROGRESS"
       }
     }

   請稍候片刻，再嘗試驗證建立程序是否已完成。

   已完成

   機構已佈建完成後，長時間執行作業的狀態會變為 FINISHED。例如：

   {
     "name": "organizations/org_name/operations/long_running_operation_ID",
     "metadata": {
       "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
       "operationType": "INSERT",
       "targetResourceName": "organizations/org_name",
       "state": "FINISHED"
     },
     "done": true,
     "response": {
       "@type": "type.googleapis.com/google.cloud.apigee.v1.Organization",
       "name": "org_name",
       "displayName": "display_name",
       "description": "description",
       "createdAt": "1600817805771",
       "lastModifiedAt": "1600817805771",
       "properties": {
         "property": [
           {
             "name": "features.hybrid.enabled",
             "value": "true"
           },
           {
             "name": "features.mart.connect.enabled",
             "value": "true"
           }
         ]
       },
       "analyticsRegion": "us-central1",
       "runtimeType": "HYBRID",
       "subscriptionType": "TRIAL"
     }
   }

   如果您未輸入說明，回應中就不會顯示該欄位。

查看機構詳細資料

您可以使用 Apigee API 查看所建立機構的中繼資料詳細資料。您也可以使用 API 列出 Google Cloud 帳戶可存取的所有機構。如要執行這些動作，請使用 organizations API。

在嘗試使用 API 前，請先重新整理授權權杖：

TOKEN=$(gcloud auth print-access-token)

https://apigee.googleapis.com/v1/organizations/org_name

curl -H "Authorization: Bearer $TOKEN" \
  "https://apigee.googleapis.com/v1/organizations/hybrid-example"

{
  "name": "organizations/org_name/operations/long_running_operation_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "INSERT",
    "targetResourceName": "org_name",
    "state": "FINISHED"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.Organization",
    "name": "org_name",
    "displayName": "display_name",
    "description": "description",
    "createdAt": "1600817805771",
    "lastModifiedAt": "1600817805771",
    "properties": {
      "property": [
        {
          "name": "features.hybrid.enabled",
          "value": "true"
        },
        {
          "name": "features.mart.connect.enabled",
          "value": "true"
        }
      ]
    },
    "analyticsRegion": "us-central1",
    "runtimeType": "HYBRID",
    "subscriptionType": "TRIAL"
  }
}

https://apigee.googleapis.com/v1/organizations

curl -H "Authorization: Bearer $TOKEN" "https://apigee.googleapis.com/v1/organizations"

{
  "organizations": [
    {
      "organization": "hybrid-example",
      "projectIds": [
        "hybrid-example"
      ]
    }
  ]
}

排解建立機構的問題

使用 Create organizations API 建立機構時，您可能會收到錯誤回應。回應如下所示：

{
  "error": {
    "code": HTTP_error_code,
    "message": "short_error_message",
    "status": "high_level_error_type",
    "details": [
      {
        "@type": "specific_error_type",
        "detail": "expanded_error_description"
      }
    ]
  }
}

以下範例顯示常見錯誤的回應：機構 ID 包含非法字元 (機構 ID 中不得使用大寫字元)：

{
  "error": {
    "code": 400,
    "message": "invalid Organization ID \"MY-ORG\": \"MY-ORG\" is an invalid Organization ID",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "",
        "detail": "[ORIGINAL ERROR] generic::invalid_argument: invalid Organization ID \"MY-ORG\":
          \"My-ORG\" is an invalid Organization ID [google.rpc.error_details_ext]
          { message: \"invalid Organization ID \\\"MY-ORG\\\": \\\"MY-ORG\\\" is an invalid
          Organization ID\" }"
      }
    ]
  }
}

在這種情況下，您可以使用小寫字母重新命名機構，然後重新傳送要求。

下表列出您嘗試建立新機構時可能會收到的錯誤訊息，以及可能的解決方案：