您已建立 Google Cloud 帳戶和專案，並啟用 API。現在可以建立機構了。
修課條件
如要建立機構，你必須符合下列其中一項條件：
- 擁有評估帳戶。評估帳戶會在 60 天後失效。屆時系統會刪除該機構。
- 擁有付費帳戶
如果以上皆非，請先與 Apigee 銷售團隊聯絡，再繼續操作。
必要權限
機構建立者至少須具備 Apigee 機構管理員角色。 如果您是專案擁有者，系統會自動授予您建立機構的權限。不過，如果您將機構建立作業委派給非專案擁有者，則必須在專案中授予該使用者 Apigee 機構管理員角色。如要瞭解如何授予角色，請參閱授予、變更及撤銷資源的存取權。
如要建立及佈建新機構：
-
在指令列中取得
gcloud驗證憑證，如下列範例所示：TOKEN=$(gcloud auth print-access-token)
如要確認權杖是否已填入，請使用
echo，如下列範例所示：echo $TOKEN
這時應該會以編碼字串的形式顯示權杖。
詳情請參閱 gcloud 指令列工具總覽。
- 為機構組織的元素建立下列環境變數。您會在指令中使用這些值來建立機構。
-
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(選用) 是貴機構的易記名稱。這個值不必是專屬值，可以包含空格和特殊字元。例如「我的混合式機構」。ORG_DISPLAY_NAME="friendly_name"
如果變數名稱內容包含空格，請以雙引號括住。例如：「我的機構」
ORGANIZATION_DESCRIPTION(選用) 是指您想用來提醒自己目標的機構資訊。例如「我的第一個機構」。ORGANIZATION_DESCRIPTION="description_text"
ANALYTICS_REGION(必要) 是用於儲存 Analytics 資料的主要區域。export ANALYTICS_REGION=analytics_region
其中 analytics_region 是下列其中一項：
asia-northeast1asia-south1australia-southeast1us-central1us-east1us-west1europe-west2europe-west1選擇地理位置鄰近或符合貴機構儲存空間需求的區域。
-
RUNTIMETYPE(必要)：Apigee 機構的執行階段類型，其中 HYBRID 是使用者管理的 Apigee Hybrid 執行階段。export RUNTIMETYPE=HYBRID
-
- 將通過驗證的
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"如果建立要求成功，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。這項作業可能需要幾分鐘才能完成。如果發生錯誤，請參閱「排解機構建立問題」。
- 將長時間執行的作業 ID 儲存至環境變數。
這在日後的管理工作中會很實用。
語法
export LONG_RUNNING_OPERATION_ID=long_running_operation_ID
範例
export LONG_RUNNING_OPERATION_ID=6abc8a72-46de-f9da-bcfe-70d9ab347e4f
- 您可以檢查 Apigee 在初始建立要求中傳回 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 帳戶有權存取的所有機構。如要執行這些動作，請使用機構 API。
嘗試使用 API 前，請先重新整理授權權杖：
TOKEN=$(gcloud auth print-access-token)
取得機構詳細資料
如要取得單一機構的詳細資料：
向下列 Get organizations API 端點傳送 GET 要求 (不含主體)：
https://apigee.googleapis.com/v1/organizations/org_name
以下範例會取得 hybrid-example 機構的詳細資料：
curl -H "Authorization: Bearer $TOKEN" \ "https://apigee.googleapis.com/v1/organizations/hybrid-example"
要求的回覆會以 JSON 格式提供指定機構的詳細資料。
以下範例顯示的回應包含 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" } }
可列出機構
如要查看 Google Cloud 帳戶可存取的所有機構清單：
將 GET 要求 (不含主體) 傳送至下列列出機構 API 端點：
https://apigee.googleapis.com/v1/organizations
例如：
curl -H "Authorization: Bearer $TOKEN" "https://apigee.googleapis.com/v1/organizations"
要求的回應會以 JSON 格式，列出您有權存取的所有啟用混合式功能的機構。
以下範例顯示包含單一機構的回應，即 hybrid-example：
{
"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\" }" } ] } }
在這種情況下，您可以將機構重新命名為小寫字母，然後重新傳送要求。
下表列出您嘗試建立新機構時可能收到的錯誤訊息，以及可能的解決方案：
| 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 專案 (在「步驟 2：建立 Google Cloud 專案」中建立) 啟用混合式功能。這可能表示帳單有問題，或是 Google Cloud 帳戶發生其他錯誤。詳情請洽詢 Apigee 銷售團隊。 |
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 所述。 |
409 |
Organization already exists |
您嘗試為 Google Cloud 專案建立多個機構。每個專案只能建立一個機構。 |
409 |
Org proposed_org_name already exists |
您嘗試建立的機構與現有機構的 ID 相同。所有混合式客戶的機構 ID 不得重複。重新提交新的提議機構 ID，例如在先前嘗試的 ID 結尾附加數值。 |