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

步驟 4：建立機構

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

修課條件

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

擁有 Google Cloud 帳戶。根據預設，Google Cloud 帳戶可讓您建立未付費的評估 Apigee 機構。評估機構會在 60 天後失效。屆時系統會刪除該機構。
擁有 Google Cloud 帳戶，並在 Google Cloud 專案和帳單帳戶中啟用付費 Apigee 訂閱方案。付費訂閱方案可讓您建立完整的可擴充 Apigee 實作項目。如要購買付費帳戶並啟用訂閱方案，請與 Apigee 銷售團隊聯絡。

關於建立機構

建立機構後，您會將機構繫結至 Google Cloud 專案。將機構繫結至 Google Cloud 專案的程序稱為「佈建」 (這只是「設定」的別稱)。

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

全新：您無法佈建現有的 Apigee 機構。您必須建立新的混合式機構。
熟悉：已啟用混合式功能的機構與傳統 Apigee 機構類似，但會繫結至 Google Cloud 專案。(這與 Google Cloud 組織或 Apigee 組織不同)。
單一：您只能將單一 Google Cloud 專案繫結至單一 Apigee 組織，反之亦然。

成功繫結新機構後，您可以使用 Google Cloud 控制台管理使用者和角色，同時透過混合式 API 或 UI 開發、部署及分析 API Proxy。如要進一步瞭解機構，請參閱「版本管理與術語」。

如要建立及佈建新機構：

在指令列中，使用下列指令取得 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%
```
這時應該會以編碼字串的形式顯示權杖。

請確認您已使用下列指令定義必要的環境變數：

echo ${PROJECT_ID}
echo ${ORG_NAME}
echo ${ORG_DISPLAY_NAME}
echo ${ORGANIZATION_DESCRIPTION}
echo ${ANALYTICS_REGION}
echo ${RUNTIMETYPE}

如有需要，請為機構的元素建立或重新定義下列環境變數。您會在建立機構的指令中使用這些值。

PROJECT_ID(必要) 是要繫結至新混合式啟用組織的 Google Cloud 專案。這是 Google 在「步驟 2：建立 Google Cloud 專案」中為您產生的 ID。
```
export PROJECT_ID=your_project_id
```
注意：請勿在專案 ID 後面加上半形句號。
ORG_NAME(必填)：您要為啟用混合式功能的機構使用的程式輔助 ID。
注意：機構名稱必須與 Google Cloud 專案 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-northeast1`	`asia-south1`	`asia-east1`	`asia-southeast1`
`australia-southeast1`	`us-central1`	`us-east1`	`us-west1`
`asia-southeast2`	`europe-west1`	`europe-west2`

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

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

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

將通過驗證的 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"
```
提示： 前一個程式碼範例中的引號結構 ("'") 是將環境變數的值傳遞至 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

您可以檢查 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": "ORG_DISPLAY_NAME",
    "description": "ORGANIZATION_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 查看所建立機構的中繼資料詳細資訊。您也可以使用 API 列出 Google Cloud 帳戶有權存取的所有機構。如要執行這些動作，請使用機構 API。

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

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

取得機構詳細資料

如要取得單一機構的詳細資料：

向下列 Get organizations API 端點傳送 GET 要求 (不含主體)：

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

以下範例會取得 $ORG_NAME 機構的詳細資料：在本範例中，$ORG_NAME 會設為「apigee-example」。

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

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

以下範例顯示的回應包含 apigee-example 機構的詳細資料：

{
  "name": "apigee-example",
  "displayName": "apigee-example-org",
  "description": "Apigee Example Org",
  "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": {}
  }
}

可列出機構

如要查看 Google Cloud 帳戶可存取的所有機構清單：

將 GET 要求 (不含主體) 傳送至下列列出機構 API 端點：

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

例如：

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

要求的回應會以 JSON 格式，列出您有權存取的所有啟用混合式功能的機構。

以下範例顯示包含單一機構的回應，即 apigee-example：

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

排解機構建立問題

使用 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 結尾附加數值。

1 2 3 4 (下一步) 步驟 5：建立環境群組