4단계: 조직 만들기

Google Cloud 계정 및 프로젝트를 만들고 API를 사용 설정했습니다. 이제 조직을 만들 수 있습니다.

기본 요건

조직을 만들려면 다음 조건 중 하나를 충족해야 합니다.

평가 계정이 있어야 합니다. 평가 계정은 60일 후에 만료됩니다. 이때 조직은 삭제됩니다.
유료 계정 소지

둘 모두에 해당하지 않으면 Apigee 영업팀에 문의하여 계속하세요.

조직 만들기 정보

조직을 만들면 Google Cloud 프로젝트에 결합됩니다. 조직을 Google Cloud 프로젝트에 결합하는 과정을 프로비저닝(설정의 전문 용어)이라고 합니다.

조직을 프로비저닝할 때는 다음 사항에 유의하세요.

새로 만들기: 기존 Apigee 조직을 프로비저닝할 수 없습니다. 새로운 하이브리드 전용 조직을 새로 만들어야 합니다.
친숙함: 하이브리드 지원 조직은 Google Cloud 프로젝트에 결합된다는 점을 제외하면 기존 Apigee 조직과 유사합니다. Google Cloud 조직 또는 Apigee 조직과는 다릅니다.
단일: 단일 Google Cloud 프로젝트를 단일 Apigee 조직에만 결합할 수 있으며 그 반대의 경우도 마찬가지입니다.

새 조직을 성공적으로 결합한 후에는 하이브리드 API 또는 UI를 사용하여 API 프록시를 개발, 배포, 분석하는 동안 Google Cloud 콘솔을 통해 사용자와 역할을 관리할 수 있습니다. 조직에 대한 자세한 내용은 버전 관리 및 용어를 참조하세요.

새 조직을 만들고 프로비저닝하려면 다음 절차를 따르세요.

다음 예시와 같이 명령줄에서 gcloud 인증 사용자 인증 정보를 가져옵니다.
```
TOKEN=$(gcloud auth print-access-token)
```
토큰이 입력되었는지 확인하려면 다음 예시와 같이 echo를 사용합니다.
```
echo $TOKEN
```
그러면 토큰이 인코딩된 문자열로 표시됩니다.

자세한 내용은 gcloud 명령줄 도구 개요를 참조하세요.

조직 요소에 다음과 같은 환경 변수를 만듭니다. 이를 명령어에 사용하여 조직을 만듭니다.

PROJECT_ID(필수)는 새 하이브리드 지원 조직에 결합할 Google Cloud 프로젝트입니다. 이 ID는 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 Hybrid 런타임입니다.
```
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

초기 생성 요청에서 ID Apigee가 반환한 장기 실행 작업의 상태를 확인할 수 있습니다. 이를 위해 작업 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

조직이 프로비저닝되면 장기 실행 작업 상태는 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)

조직 세부정보 가져오기

단일 조직에 대한 세부정보를 확인하려면 다음 절차를 따르세요.

다음 Get Organizations API 엔드포인트에 본문 없이 GET 요청을 보냅니다.

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 계정에 액세스 권한이 있는 모든 조직 목록을 가져오려면 다음 안내를 따르세요.

다음 List Organizations API 엔드포인트에 본문 없이 GET 요청을 보냅니다.

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 프로젝트용으로 두 개 이상의 조직을 만들려고 했습니다. 프로젝트당 하나의 조직만 만들 수 있습니다.
`409`	`Org proposed_org_name already exists`	이미 존재하는 조직과 동일한 ID를 가지는 조직을 만들려고 했습니다. 조직 ID는 모든 하이브리드 고객에서 고유해야 합니다. 새로 제안된 조직 ID로 다시 제출합니다(예: 시도한 이전 ID의 끝에 숫자 값을 추가).

다음 단계

1 2 3 4 (다음) 5단계: 환경 그룹 만들기