ステップ 4: 組織を作成する

Google Cloud アカウントとプロジェクトを作成し、API を有効にしました。これで、組織を作成できます。

前提条件

組織を作成するには、次のいずれかの条件を満たしている必要があります。

  • 評価アカウントを持っている。評価アカウントは 60 日後に有効期限が切れます。期限を迎えた時点で削除されます。
  • 有料アカウントを保有している

どちらにも該当しない場合は、続行する前に Apigee の販売担当者にお問い合わせください。

必要な権限

組織作成者には、少なくとも Apigee 組織管理者ロールが必要です。プロジェクト オーナーであれば、組織を作成する権限が自動的に付与されます。また、組織の作成をプロジェクト オーナー以外のユーザーに委任する場合は、そのユーザーにプロジェクトの Apigee 組織管理者ロールを付与する必要があります。ロールの付与については、リソースへのアクセス権の付与、変更、取り消しをご覧ください。

新しい組織を作成してプロビジョニングするには:

  1. 次の例に示すように、コマンドラインで gcloud 認証情報を取得します:

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

    トークンにデータが入力されていることを確認するには、次の例のように echo を使用します。

    echo $TOKEN

    エンコードされた文字列としてトークンが表示されるはずです。

    詳細については、gcloud コマンドライン ツールの概要をご覧ください。

  2. 組織の要素用に、次の環境変数を作成します。これらの変数は、組織を作成するコマンドの中で使用します。
    • PROJECT_ID(必須)は、新しいハイブリッド対応組織にバインドする Google Cloud プロジェクトです。これは、ステップ 2: Google Cloud プロジェクトを作成するで生成された ID です。
      export PROJECT_ID=your_project_id

      末尾にピリオドが付いたプロジェクト ID 名

    • ORG_NAME(必須)は、ハイブリッド対応組織に必要なプログラマティック ID です。
      export ORG_NAME=$PROJECT_ID
    • ORG_DISPLAY_NAME(省略可)は、ユーザーにわかりやすい形の組織名です。この値は一意である必要はなく、スペースと特殊文字を使用できます。例: "My Hybrid Organization"
      ORG_DISPLAY_NAME="friendly_name"

      スペースが含まれる変数名は、二重引用符で囲む必要があります。例: "My Organization"

    • ORGANIZATION_DESCRIPTION(省略可)は、組織に関する情報で、目的を書き留めておくために使用できます。例: "My first organization"
      ORGANIZATION_DESCRIPTION="description_text"
    • ANALYTICS_REGION(必須)は、分析データ ストレージのプライマリ リージョンです。
      export ANALYTICS_REGION=analytics_region

      ここで、analytics_region は次のいずれかです。

      asia-northeast1 asia-south1 australia-southeast1
      us-central1 us-east1 us-west1
      europe-west2 europe-west1

      地理的に近いリージョンか、組織のストレージ要件を満たすリージョンを選択します。

    • RUNTIMETYPE(必須)は、Apigee 組織のランタイム タイプです。ここで、HYBRID はユーザーが管理する Apigee ハイブリッド ランタイムです。
      export RUNTIMETYPE=HYBRID
  3. 認証された 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"

    作成リクエストが成功すると、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. 最初の作成リクエストで 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 でまだ組織が作成中の場合は、ステータス 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

    組織がプロビジョニングされると、長時間実行オペレーションの状態が 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": "display_name",
        "description": "description",
        "createdAt": "1600817805771",
        "lastModifiedAt": "1600817805771",
        "properties": {
          "property": [
            {
              "name": "features.hybrid.enabled",
              "value": "true"
            },
            {
              "name": "features.mart.connect.enabled",
              "value": "true"
            }
          ]
        },
        "analyticsRegion": "us-central1",
        "runtimeType": "HYBRID",
        "subscriptionType": "TRIAL"
      }
    }

    説明を入力しなかった場合、このフィールドはレスポンスに表示されません。

組織の詳細情報を表示する

Apigee API を使用して作成した組織のメタデータの詳細を表示できます。また、API を使用して、Google Cloud アカウントでアクセスできるすべての組織を一覧表示することも可能です。これらの操作を行うには、organizations API を使用します。

API を試す前に認証トークンを更新してください。

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

組織の詳細情報を取得する

1 つの組織に関する詳細情報を取得するには:

GET リクエスト(本文なし)を次の Get Organizations API エンドポイントに送信します。

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

次の例では、hybrid-example という組織の詳細を取得しています。

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

リクエストのレスポンスでは、指定した組織に関する詳細情報が JSON 形式で返されます。

次の例では、hybrid-example という組織に関する詳細情報を含むレスポンスを示します。

{
  "name": "organizations/org_name/operations/long_running_operation_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.OperationMetadata",
    "operationType": "INSERT",
    "targetResourceName": "org_name",
    "state": "FINISHED"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.apigee.v1.Organization",
    "name": "org_name",
    "displayName": "display_name",
    "description": "description",
    "createdAt": "1600817805771",
    "lastModifiedAt": "1600817805771",
    "properties": {
      "property": [
        {
          "name": "features.hybrid.enabled",
          "value": "true"
        },
        {
          "name": "features.mart.connect.enabled",
          "value": "true"
        }
      ]
    },
    "analyticsRegion": "us-central1",
    "runtimeType": "HYBRID",
    "subscriptionType": "TRIAL"
  }
}

組織の一覧表示

使用している Google Cloud アカウントにアクセス権がある全組織一覧を取得するには:

GET リクエスト(本文なし)を次の List organizations API エンドポイントに送信します。

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

次に例を示します。

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

リクエストのレスポンスでは、アクセス可能なハイブリッド対応組織の配列が JSON 形式で返されます。

次の例では、hybrid-example という単一の組織を含むレスポンスを示します。

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

組織作成のトラブルシューティング

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 ステップ 2: Google Cloud プロジェクトの作成で作成した 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 プロジェクトに複数の組織を作成しようとしました。1 つのプロジェクトに作成できる組織は 1 つのみです。
409 Org proposed_org_name already exists 既存の ID と同じ ID で組織を作成しようとしました。組織 ID はすべてのハイブリッド ユーザーの間で一意にする必要があります。提案された新しい組織 ID で再送信します。たとえば、前に試した ID の末尾に数値を追加します。
1 2 3 4 (次)ステップ 5: DNS を構成する 6