步驟 2：建立機構

Version 1.15 (latest)

   Supported versions:

• v1.15 (latest)                        
• v1.14                        
• v1.13                         
• List of supported versions

   Unsupported versions:

• v1.12                         
• v1.11                         
• v1.10                                      
• v1.9                                         
• v1.8                                         
• v1.7                                         
• v1.6                                         
• v1.5                                         
• v1.4                                         
• v1.3                                         
• v1.2                                         
• v1.1                                         

在這個步驟中，您會建立 Apigee 組織。

注意： Apigee 機構是 Apigee 中的頂層容器。Apigee 機構包含所有 API Proxy 和相關資源。Apigee 機構與 Google Cloud 機構不同。

• 如要瞭解 Apigee 機構的相關資訊，請參閱「機構架構」。
• 如要瞭解 Google Cloud 機構，請參閱「機構」。

關於建立機構

佈建機構時，請注意下列事項：

• 您無法在現有的 Apigee 機構中佈建 Apigee Hybrid。 您必須建立新機構，且機構名稱須與 Google Cloud 專案 ID 相符。
• 機構只能連結至單一 Google Cloud 專案。

如要建立及佈建新機構：

注意： 如果您使用 Apigee 評估帳戶，建立的機構會在 60 天後失效。屆時系統會刪除該機構。

如果發生這種情況，您可能會遇到下列錯誤："Project <my-project> doesn't have an Apigee organization provisioned." 如要解決這項錯誤，請按照步驟建立新機構並佈建。

1. 在指令列中，使用下列指令取得 gcloud 驗證憑證：

   Linux / MacOS

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

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

   echo $TOKEN

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

   Windows

   for /f "tokens=*" %a in ('gcloud auth print-access-token') do set TOKEN=%a

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

   echo %TOKEN%

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

2. 在步驟 1 中，您建立了 PROJECT_ID 環境變數。新增下列環境變數。選取與貴機構類型對應的分頁：沒有資料落地或 有資料落地：

   沒有資料落地設定

   Linux / MacOS

   export ORG_NAME=$PROJECT_ID
   export ANALYTICS_REGION="ANALYTICS_REGION"
   export RUNTIMETYPE=HYBRID

   Windows

   set ORG_NAME=$PROJECT_ID
   set ANALYTICS_REGION="ANALYTICS_REGION"
   set RUNTIMETYPE=HYBRID

   提示：使用 echo %variable-name% 指令確認環境變數是否已正確設定。

   地點：

   • ORG_NAME (必要)：這個值必須與 PROJECT_ID 相符。
   • ANALYTICS_REGION (必填)：儲存 Analytics 資料的主要區域。如需可用的 Apigee API Analytics 區域清單，請參閱 Apigee 位置。
   • RUNTIMETYPE (必要)：必須設為 HYBRID。

   資料落地

   Linux / MacOS

   export ORG_NAME=$PROJECT_ID
   export RUNTIMETYPE=HYBRID
   export CONTROL_PLANE_LOCATION="YOUR_CONTROL_PLANE_LOCATION"
   export CONSUMER_DATA_REGION="YOUR_CONSUMER_DATA_REGION"
   export BILLING_TYPE="SUBSCRIPTION"

   Windows

   set ORG_NAME=$PROJECT_ID
   set RUNTIMETYPE=HYBRID
   set CONTROL_PLANE_LOCATION="YOUR_CONTROL_PLANE_LOCATION"
   set CONSUMER_DATA_REGION="YOUR_CONSUMER_DATA_REGION"
   set BILLING_TYPE="SUBSCRIPTION"

   提示：使用 echo %variable-name% 指令確認環境變數是否已正確設定。

   地點：

   • ORG_NAME：這個值必須符合 PROJECT_ID。
   • RUNTIMETYPE：必須設為 HYBRID。
   • CONTROL_PLANE_LOCATION：儲存客戶核心內容 (例如 Proxy 組合) 的位置。如需清單，請參閱「可用的 Apigee API 控制平面區域」。
   • CONSUMER_DATA_REGION：控制層區域的子區域。您必須同時指定 CONTROL_PLANE_LOCATION 和 CONSUMER_DATA_REGION。如需可用的消費者資料區域清單，請參閱 Apigee 位置。
   • BILLING_TYPE：必須設為 "SUBSCRIPTION"。這是 Apigee Hybrid 機構的帳單類型。詳情請參閱「訂閱授權」。

   例如：

   export ORG_NAME=$PROJECT_ID
   export RUNTIMETYPE=HYBRID
   export CONSUMER_DATA_REGION="us-west1"
   export CONTROL_PLANE_LOCATION="us"
   export BILLING_TYPE="SUBSCRIPTION"
   

3. 呼叫下列 Apigee API 來建立機構：

   沒有資料落地設定

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

   資料落地

   curl -H "Authorization: Bearer $TOKEN" -X POST -H "content-type:application/json" \
     -d '{
       "name":"'"$ORG_NAME"'",
       "billingType":"'"$BILLING_TYPE"'",
       "runtimeType":"'"$RUNTIMETYPE"'",
       "apiConsumerDataLocation":"'"$CONSUMER_DATA_REGION"'"
     }' \
     "https://$CONTROL_PLANE_LOCATION-apigee.googleapis.com/v1/organizations?parent=projects/$PROJECT_ID"

   提示： 如要傳遞 JSON 內文中的環境變數值，請使用先前程式碼範例中的引號結構 ("'")。

   如果建立要求成功，Organizations 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",
       "description": "",
       "createdAt": "1626237148461",
       "lastModifiedAt": "1626237149384",
       "properties": {
         "property": [
           {
             "name": "features.hybrid.enabled",
             "value": "true"
           },
           {
             "name": "features.mart.connect.enabled",
             "value": "true"
           }
         ]
       },
       "analyticsRegion": "ANALYTICS_REGION",
       "runtimeType": "HYBRID",
       "subscriptionType": "TRIAL",
       "state": "ACTIVE",
       "billingType": "EVALUATION",
       "expiresAt": "1631421073171",
       "addonsConfig": {
         "advancedApiOpsConfig": {},
         "integrationConfig": {},
         "monetizationConfig": {}
       }
     }
   }

   資料落地

   curl -H "Authorization: Bearer $TOKEN" \
     "https://$CONTROL_PLANE_LOCATION-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",
       "progress": {
         "percentDone": 30
       }
     }
   }

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

   已完成

   機構佈建完成後，長時間執行的作業狀態會是 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",
       "description": "",
       "createdAt": "1626237148461",
       "lastModifiedAt": "1626237149384",
       "properties": {
         "property": [
           {
             "name": "features.hybrid.enabled",
             "value": "true"
           },
           {
             "name": "features.mart.connect.enabled",
             "value": "true"
           }
         ]
       },
       "analyticsRegion": "ANALYTICS_REGION",
       "runtimeType": "HYBRID",
       "subscriptionType": "TRIAL",
       "state": "ACTIVE",
       "billingType": "SUBSCRIPTION",
       "apiConsumerDataLocation": "CONSUMER_DATA_REGION",
       "expiresAt": "1631421073171",
       "addonsConfig": {
         "advancedApiOpsConfig": {},
         "integrationConfig": {},
         "monetizationConfig": {}
       }
     }
   }

6. 您可以使用 Apigee 機構 API，在機構建立後擷取相關資訊。

   例如：

   沒有資料落地設定

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

   要求的回覆會以 JSON 格式提供指定機構的詳細資料。

   {
     "name": "apigee-example",
     "createdAt": "1626237148461",
     "lastModifiedAt": "1626237149384",
     "properties": {
       "property": [
         {
           "name": "features.hybrid.enabled",
           "value": "true"
         },
         {
           "name": "features.mart.connect.enabled",
           "value": "true"
         }
       ]
     },
     "analyticsRegion": "us-west1",
     "runtimeType": "HYBRID",
     "subscriptionType": "PAID",
     "projectId": "my-project",
     "state": "ACTIVE",
     "billingType": "SUBSCRIPTION",
     "expiresAt": "1631421073171",
     "addonsConfig": {
       "advancedApiOpsConfig": {},
       "integrationConfig": {},
       "monetizationConfig": {}
     }
   }

   資料落地

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

   要求的回覆會以 JSON 格式提供指定機構的詳細資料。

   {
     "name": "apigee-example",
     "createdAt": "1626237148461",
     "lastModifiedAt": "1626237149384",
     "properties": {
       "property": [
         {
           "name": "features.hybrid.enabled",
           "value": "true"
         },
         {
           "name": "features.mart.connect.enabled",
           "value": "true"
         }
       ]
     },
     "analyticsRegion": "us-west1",
     "runtimeType": "HYBRID",
     "subscriptionType": "PAID",
     "projectId": "my-project",
     "state": "ACTIVE",
     "billingType": "SUBSCRIPTION",
     "expiresAt": "1631421073171",
     "addonsConfig": {
       "advancedApiOpsConfig": {},
       "integrationConfig": {},
       "monetizationConfig": {}
     }
   }

排解機構建立問題

使用 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"
      }
    ]
  }
}

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

HTTP 錯誤代碼	HTTP 錯誤	說明
400	Invalid JSON payload received	要求中的資料結構含有語法錯誤，或是端點路徑有誤。
400	Invalid organization ID	您要求的機構 ID 不得包含大寫字母或任何特殊字元 (連字號除外)。只能使用小寫英文字母、數字和/或連字號。長度上限為 32 個半形字元。
400	Unsupported analytics region	您未在要求主體中指定 analyticsRegion 的值，或指定的值不是有效選項。
400	Does not have an Apigee entitlement	您的 Google Cloud 專案尚未啟用混合式功能。這可能表示帳單有問題，或是 Google Cloud 帳戶發生其他錯誤。詳情請洽詢 Apigee 銷售團隊。
400	'global' violates constraint in constraints/gcp.resourceLocations on the resource projects/PROJECT_ID, Control Plane Region	您嘗試建立的機構可能沒有付費訂閱方案資格。Apigee Hybrid 的 EVAL 類型機構不支援 資料落地。
400	runtimeType HYBRID is not supported for PAYG_V2, use CLOUD instead: invalid argument	您嘗試在具有「即付即用」授權的專案中建立機構。如有機構授權相關問題，請洽詢 Google Cloud 帳戶代表。
401	Request had invalid authentication credentials	您的gcloud驗證權杖無效或過時，或是您未在要求中加入驗證權杖。產生新權杖，然後重新傳送地址。
403	Permission denied on resource project PROJECT_ID	您可能傳送的要求含有錯誤的專案 ID 或路徑。
403	Unable to retrieve project information	尚未建立或佈建機構。您可以向 Operations API 發出要求，檢查長時間執行作業的狀態，如步驟 5 所述。
403	Permission denied on resource project organizations/PROJECT_ID/deployedIngressConfig	您嘗試建立機構，但機構沒有正確的權利。如有機構授權相關問題，請洽詢 Google Cloud 帳戶代表。
409	Organization already exists	您嘗試為 Google Cloud 專案建立多個機構。每個專案只能建立一個機構。
409	Org PROPOSED_ORG_NAME already exists	您嘗試建立的機構與現有機構的 ID 相同。所有混合式客戶的機構 ID 不得重複。重新提交，並提供新的建議機構 ID，例如在先前嘗試的 ID 結尾附加數值。

後續步驟

請前往步驟 3：建立環境群組。