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

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

前提条件

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

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

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

組織の作成について

組織を作成したら、その組織を Google Cloud プロジェクトにバインドします。組織を Google Cloud プロジェクトにバインドするプロセスは、「プロビジョニング」（「セットアップ」を専門的に表現したもの）と呼ばれています。

組織をプロビジョニングする際は、次の点に留意してください。

まったく新規: 既存の Apigee 組織をプロビジョニングすることはできません。新しくハイブリッド専用の組織を作成する必要があります。
理解している: ハイブリッド対応組織は、Google Cloud プロジェクトにバインドされていることを除けば従来の Apigee 組織と似ています（Google Cloud 組織および Apigee 組織とは別のものです）。
単一: Google Cloud プロジェクトと Apigee 組織のバインドは 1 対 1 でのみ行えます。

新しい組織をバインドした後、ユーザーとロールの管理は Google Cloud コンソールで行い、API プロキシの開発、デプロイ、分析は Hybrid API または UI で行います。組織の詳細については、バージョニングと用語をご覧ください。

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

次の例のように、コマンドラインで gcloud 認証情報を取得します。
```
TOKEN=$(gcloud auth print-access-token)
```
トークンにデータが入力されていることを確認するには、次の例のように echo を使用します。
```
echo $TOKEN
```
エンコードされた文字列としてトークンが表示されるはずです。

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

組織の要素用に、次の環境変数を作成します。これらの変数は、組織を作成するコマンドの中で使用します。

PROJECT_ID（必須）は、新しいハイブリッド対応組織にバインドする Google Cloud プロジェクトです。これは、ステップ 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（省略可）は、ユーザーにわかりやすい形の組織名です。この値は一意である必要はなく、スペースと特殊文字を使用できます。例: "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
```

ヒント: echo $variable-name コマンドを使用して、環境変数が正しく設定されていることを確認します。

認証された POST リクエストを Create Organizations API に送信します。
注: ハイブリッド対応組織を作成した後は、その組織の削除、組織 ID の変更、その組織にバインドされた Google Cloud プロジェクトの変更はできません。別の Google Cloud プロジェクトに移行する必要がある場合は、Apigee 販売担当者に連絡して、プロジェクトを廃止し、新しいプロジェクトの利用資格を提供します。
次の例は、組織を作成するリクエストの構造を示しています。
```
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 の長時間実行オペレーションのステータスを確認できます。この操作を行うには、オペレーション 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: 環境グループを作成する