步驟 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"

    建立要求成功後，組織 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"
  }
}

    您應稍等一下，再嘗試驗證建立程序是否已完成。

    已完成

    機構已佈建完成後，長時間執行作業的狀態會變為 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": "apigee-example",
  "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": "apigee-example",
  "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 您嘗試建立的機構可能沒有付費訂閱的授權。EVAL 類型的 Apigee Hybrid 機構不支援 資料落地。
400 runtimeType HYBRID is not supported for PAYG_V2, use CLOUD instead: invalid argument 您嘗試在具備「即付即用」(PAYG) 授權的專案中建立機構。如有任何機構授權問題，請與 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，例如在先前嘗試的 ID 結尾處附加數值。

後續步驟

請參閱步驟 3：建立環境群組。