步驟 2：建立機構

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

如要建立及佈建新機構：

  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

    地點：

    • 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"

    地點：

    • 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"

    如果建立要求成功，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：建立環境群組。