步驟 4：建立機構

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

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

修課條件

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

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

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

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

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

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

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

   echo $TOKEN

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

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

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

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

   curl -H "Authorization: Bearer $TOKEN" -X POST -H "content-type:application/json" \
     -d '{
       "name":"proposed_org_ID",
       "displayName":"display_name",
       "description":"organization_description",
       "runtimeType":"runtime_type",
       "analyticsRegion":"analytics_region"
     }' \
     "https://apigee.googleapis.com/v1/organizations?parent=projects/project_ID"

   其中：

   • (必要) proposed_org_ID 是您要為啟用混合型機構設定的程式輔助 ID。例如 my-hybrid-org。

     Apigee 建議您使用與您在步驟 2：建立 Google Cloud 專案中建立的 Google Cloud 專案 ID 相同的 ID，但您也可以使用其他 ID。

   • (必填) runtime_type 是 Apigee 機構的執行階段類型，其中 HYBRID 是使用者管理的 Apigee Hybrid 執行階段。
   • (必填) analytics_region 是數據分析資料儲存空間的主要區域。請選擇下列其中一個選項：

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

     我們提供這個選項，方便您選擇地理位置相近的區域，或滿足貴機構的其他儲存需求。

   • (必要) project_ID 是您要與新的混合型機構綁定 Google Cloud 專案。這是 Google 在步驟 2：建立 Google Cloud 專案中為您產生的 ID。
   • (選用) display_name 是貴機構的使用者友善名稱。這個值不必是唯一值，且可以包含空格和特殊字元。例如「我的混合型組織」。
   • (選用) organization_description 是您想用來提醒機構用途的相關資訊。例如「我的第一個組織」。

   建立要求成功後，Organizations API 應會傳回類似以下的訊息：

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

   其中：

   • long_running_operation_ID 是長時間執行的非同步作業 UUID。您可以使用這個 ID 查看建立機構的要求狀態 (稍後說明)。
   • organization_ID 是目前正在建立的新機構 ID。

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

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

3. 您可以檢查長時間執行作業的狀態，該作業的 ID 會在初始建立要求中傳回。如要執行這項操作，請使用 Operations API，如以下範例所示：

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

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

   已完成

   組織已佈建完成後，長時間執行作業的狀態會是 FINISHED，如以下範例所示：

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

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

   恭喜！您已建立新機構，並可開始使用。您可以繼續進行步驟 5：新增環境。

   IN_PROGRESS

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

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

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

排解建立機構的問題

使用 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": "type.googleapis.com/google.rpc.DebugInfo",
        "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\" }"
      }
    ]
  }
}

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

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

取得機構資訊

您可以取得帳戶可存取的所有機構清單，也可以透過 ID 取得特定機構的詳細資料。如要執行這些動作，請使用 organizations API。

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

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

{
  "organizations": [
    {
      "organization": "my-org-42",
      "projectIds": [
        "my-project"
      ]
    }
  ]
}

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

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

{
  "name": "my-org-42",
  "createdAt": "1572550611",
  "lastModifiedAt": "1572550611",
  "environments": [
    "my-environment"
  ],
  "analyticsRegion": "us-east1"
}