API 구성 만들기

기본 요건

API 구성을 만들려면 먼저 다음을 확인합니다.

API 구성 ID 요구사항

아래 표시된 많은 gcloud 명령에서는 CONFIG_ID 형식으로 API 구성의 ID를 지정해야 합니다. API 게이트웨이는 API 구성 ID에 대해 다음 요구사항을 적용합니다.

  • 최대 63자여야 합니다.
  • 소문자, 숫자, 대시만 포함해야 합니다.
  • 대시로 시작해서는 안 됩니다.
  • 밑줄을 포함해서는 안 됩니다.

API 구성 만들기

API 구성을 만들기 위해 gcloud 명령줄 도구를 사용하여 API 정의를 업로드합니다. API 정의를 업로드할 때는 API 이름을 지정해야 합니다. API가 아직 API 게이트웨이에 없으면 이 명령어로 API도 생성됩니다.

API 구성을 만들려면 다음 안내를 따르세요.

  1. API 정의가 포함된 디렉터리로 변경합니다.

    API 정의에 대해 OpenAPI 사양 만들기에 대한 자세한 내용은 OpenAPI 개요빠른 시작: API 게이트웨이에 API 배포를 참조하세요.

    gRPC 서비스 정의 및 API 정의 구성에 대한 자세한 내용은 gRPC 서비스 구성API 게이트웨이 및 gRPC용 Cloud Run 시작하기를 참조하세요.

  2. 잘못된 프로젝트에 서비스가 만들어지지 않도록 다음 명령어로 반환되는 프로젝트 ID의 유효성을 검사합니다.

    gcloud config list project

    기본 프로젝트를 변경해야 하는 경우 다음 명령어를 실행하고 PROJECT_ID를 서비스를 만들 Google Cloud 프로젝트의 ID로 바꿉니다.

    gcloud config set project PROJECT_ID
  3. api-configs create 명령어 도움말을 확인합니다.

    gcloud api-gateway api-configs create --help
  4. 다음 명령어를 실행하여 API 구성을 만듭니다.

    gcloud api-gateway api-configs create CONFIG_ID \
      --api=API_ID --openapi-spec=API_DEFINITION \
      --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL

    각 항목의 의미는 다음과 같습니다.

    • CONFIG_ID는 새 API 구성의 ID를 지정합니다.
    • API_ID는 이 API 구성과 연결된 API 게이트웨이 API의 ID를 지정합니다. API가 아직 없으면 이 명령어로 생성됩니다.
    • API_DEFINITION은 API 정의가 포함된 OpenAPI 사양의 이름을 지정합니다.
    • PROJECT_ID는 Google Cloud 프로젝트 ID를 지정합니다.
    • SERVICE_ACCOUNT_EMAIL은 API 구성을 만들기 위해 명시적으로 만든 서비스 계정을 지정합니다. 자세한 내용은 서비스 계정 구성을 참조하세요.

    API 및 API 구성이 생성될 때 API 게이트웨이가 터미널에 정보를 출력합니다. API 구성이 다운스트림 시스템에 전파되기 때문에 이 작업은 완료하는 데 몇 분 정도 걸릴 수 있습니다. 복잡한 API 구성을 만들기 위해서는 최대 10분까지 걸릴 수 있습니다. 구성이 생성되는 동안에는 동일한 API에 대해 다른 구성을 만들려고 시도하지 마세요. 모든 API 구성은 한 번에 하나만 만들 수 있습니다.

  5. 성공적으로 완료되었으면 다음 명령어를 사용하여 새 API 구성에 대한 세부정보를 볼 수 있습니다.

    gcloud api-gateway api-configs describe CONFIG_ID \
      --api=API_ID --project=PROJECT_ID

    이 명령어는 다음을 반환합니다.

    createTime: '2020-02-04T18:33:11.882707149Z'
    displayName: CONFIG_ID
    gatewayConfig:
      backendConfig:
        googleServiceAccount: 1111111@developer.gserviceaccount.com
    labels: ''
    name: projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID
    serviceRollout:
      rolloutId: 2020-02-04r2
    state: ACTIVE
    updateTime: '2020-02-04T18:33:12.219323647Z'
  6. API의 관리형 서비스 이름을 사용하여 API를 사용 설정합니다. 이 값은 API 방문 페이지에 있는 API의 관리형 서비스 열에서 찾을 수 있습니다.

    gcloud services enable MANAGED_SERVICE_NAME.apigateway.PROJECT_ID.cloud.goog

    API를 만들 때 이 명령어를 한 번만 실행하면 됩니다. 나중에 API를 수정할 경우 명령어를 다시 실행할 필요가 없습니다.

gcloud 명령줄 도구에는 gcloud 참조에 설명된 옵션을 포함하여 많은 옵션이 사용됩니다. 또한 API 게이트웨이의 경우 API 구성을 만들 때 다음 옵션을 설정할 수 있습니다.

  • --async: 작업이 완료될 때까지 기다릴 필요 없이 터미널로 제어권을 즉시 반환합니다.
  • --display-name=NAME: API 구성의 표시 이름 즉, UI에 표시되는 이름을 지정합니다. 이름에 공백을 사용하지 마세요. 대신 하이픈과 밑줄을 사용하세요. 기본값은 CONFIG_ID입니다.
  • --labels=KEY1=VALUE1,KEY2=VALUE2,...: API 구성과 연결된 라벨을 지정합니다.

예를 들면 다음과 같습니다.

gcloud api-gateway api-configs create CONFIG_ID \
  --api=API_ID --openapi-spec=API_DEFINITION \
  --project=PROJECT_ID --backend-auth-service-account=SERVICE_ACCOUNT_EMAIL \
  --async --display-name=MyConfig --labels=a=1,b=2

위에 표시된 describe 명령어 또는 --format 옵션을 포함하여 list 명령어의 출력에서 라벨을 볼 수 있습니다.

gcloud api-gateway api-configs list \
  --api=API_ID --project=PROJECT_ID --format="table(name, labels)"

API 구성 나열

특정 프로젝트에 대해 API 구성을 나열하려면 다음 안내를 따르세요.

gcloud api-gateway api-configs list --project=PROJECT_ID

이 명령어는 다음을 반환합니다.

NAME                                                                DISPLAY_NAME  ROLLOUT_ID    STATE   CREATE_TIME
projects/PROJECT_ID/locations/global/apis/API_ID/configs/CONFIG_ID  CONFIG_ID     2020-02-04r0  ACTIVE  2020-02-04T16:18:02.369859863Z

프로젝트에서 특정 API의 API 구성을 나열하려면 다음 안내를 따르세요.

gcloud api-gateway api-configs list --api=API_ID --project=PROJECT_ID

프로젝트, API, 구성 ID를 사용해서 API 구성에 대해 자세한 정보를 가져옵니다.

gcloud api-gateway api-configs describe CONFIG_ID \
  --api=API_ID --project=PROJECT_ID

API 구성 업데이트

라벨 및 표시 이름 업데이트 이외에는 기존 API 구성을 수정할 수 없습니다.

기존 API 구성을 업데이트하려면 다음 gcloud를 사용합니다.

  • --display-name
  • --update-labels
  • --clear-labels
  • --remove-labels

예를 들면 다음과 같습니다.

gcloud api-gateway api-configs update CONFIG_ID \
  --api=API_ID  --project=PROJECT_ID \
  --update-labels=a=1,b=2

다음 명령어를 사용하여 모든 업데이트 옵션을 확인합니다.

gcloud api-gateway api-configs update --help

API 구성 삭제

다음 gcloud 명령어를 사용하여 기존 API 구성을 삭제합니다.

gcloud api-gateway api-configs delete CONFIG_ID --api=API_ID --project=PROJECT_ID

다음 단계