本頁面由 Cloud Translation API 翻譯而成。

步驟 2：建立機構

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

關於建立機構

如要建立及佈建新機構：

在指令列中，使用下列指令取得 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%
```
這時應該會以編碼字串的形式顯示權杖。
在步驟 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。
呼叫下列 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"
```
提示： 前一個程式碼範例中的引號結構 ("'") 是將環境變數的值傳遞至 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。這項作業可能需要幾分鐘才能完成。

如果發生錯誤，請參閱「排解機構建立問題」。

將長時間執行的作業 ID 儲存至環境變數。這在日後的管理工作中會很實用。

語法

export LONG_RUNNING_OPERATION_ID=LONG_RUNNING_OPERATION_ID

範例

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

您可以檢查建立要求傳回的長期執行作業 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": {}
    }
  }
}

您可以使用 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": "TRIAL",
  "projectId": "apigee-example",
  "state": "ACTIVE",
  "billingType": "EVALUATION",
  "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 專案 (在「步驟 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 結尾附加數值。

後續步驟

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