步驟 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 (必要)：儲存數據分析資料的主要區域。如需可用的 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 是由建立要求傳回。方法是使用作業 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": {}
  }
}

排解組織建立問題

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

Next step

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