Admin API 시작하기

리전 ID

REGION_ID는 앱을 만들 때 선택한 리전을 기준으로 Google에서 할당하는 축약된 코드입니다. 일부 리전 ID는 일반적으로 사용되는 국가 및 주/도 코드와 비슷하게 표시될 수 있지만 코드는 국가 또는 주/도와 일치하지 않습니다. 2020년 2월 이후에 생성된 앱의 경우 REGION_ID.r이 App Engine URL에 포함됩니다. 이 날짜 이전에 만든 기존 앱의 경우 URL에서 리전 ID는 선택사항입니다.

리전 ID에 대해 자세히 알아보세요.

이 가이드에서는 App Engine Admin API를 사용하여 샘플 Python 애플리케이션을 App Engine에 배포하는 방법을 설명합니다. 전반적인 프로세스를 사용하여 프로그래매틱 방식으로 앱을 관리하고 배포하는 코드를 만드는 방법을 배울 수 있습니다.

이 가이드에서 사용하는 샘플은 'Hello, World!'라는 텍스트를 표시하는 간단한 Hello World 앱으로, GitHub에서 사용할 수 있습니다. Google Cloud Console 승인에는 OAuth 클라이언트 ID와 웹브라우저가 사용됩니다. 프로세스의 개별 단계를 보여주기 위해 터미널에서 HTTP 요청을 보낼 수 있도록 cURL 명령어가 제공됩니다.

목표

  • Google Cloud Console 프로젝트에서 API를 사용 설정하고 OAuth 클라이언트 ID 사용자 인증 정보를 만듭니다.
  • App Engine 인증을 위한 액세스 토큰을 얻습니다.
  • Admin API를 사용하여 샘플 앱을 App Engine에 배포합니다.
  • 선택사항: 샘플 앱을 배포한 버전에 대한 트래픽을 구성합니다.

시작하기 전에

  • Google 계정이 있거나 이 계정을 만들어야 합니다.
  • Google Cloud CLI를 다운로드하여 설치한 다음 gcloud CLI를 초기화합니다.
    SDK 다운로드

Google Cloud 프로젝트 구성

Google Cloud 프로젝트에서 App Engine Admin API 및 Cloud Storage API를 사용 설정한 후 사용자 인증 정보를 구성합니다.

  1. Google Cloud 콘솔에서 API를 사용 설정합니다.

    API 사용 설정

  2. 마법사에서 목록에 있는 기존 프로젝트를 선택하거나 계속을 클릭하여 새 프로젝트를 만듭니다.

  3. 계속을 클릭하여 OAuth 클라이언트 ID 사용자 인증 정보를 만듭니다.

    1. OAuth 동의 화면에서 이메일 주소와 사용자에게 표시되는 제품 이름은 반드시 지정합니다.
    2. 동의 화면 설정을 저장한 다음 저장을 클릭하여 사용자 인증 정보 탭으로 전환합니다.
    3. 사용자 인증 정보 만들기를 클릭한 다음 OAuth 클라이언트 ID를 클릭하여 클라이언트 ID를 만듭니다.

    4. 웹 애플리케이션을 클릭하고 이름을 지정한 다음 https://www.google.com을 리디렉션 URI로 사용합니다.

    5. 만들기를 클릭하여 사용자 인증 정보를 저장합니다.

    6. 표시되는 클라이언트 ID는 이후 단계에서 액세스 토큰을 요청하는 데 사용되므로 기록해 둡니다.

Admin API 사용자 인증 정보를 만드는 방법에 대한 자세한 내용은 API 액세스를 참조하세요.

구성 파일 만들기

Hello World 앱 배포를 정의하는 구성 파일을 만듭니다. app.json이라는 파일에서 sourceUrl 필드에 Hello World 앱의 Cloud Storage 버킷을 정의하고 id 필드의 버전 ID를 포함하여 버전 구성 정보를 정의합니다.

{
  "deployment": {
    "files": {
      "main.py": {
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
      },
    }
  },
  "handlers": [
    {
      "script": {
        "scriptPath": "main.app"
      },
      "urlRegex": "/.*"
    }
  ],
  "runtime": "python27",
  "threadsafe": true,
  "id": "appengine-helloworld",
  "inboundServices": [
    "INBOUND_SERVICE_WARMUP"
  ]
}

예를 들면 root/python-docs-samples/appengine/standard/hello_world/app.json입니다.

HTTP 요청 승인

Admin API를 사용하여 HTTP 요청을 보낼 수 있도록 App Engine 인증을 진행합니다.

빨리 시작하려면 다음 옵션 중 하나를 사용하세요. HTTPS와 gcloud 옵션 모두 Admin API를 시범적으로 사용해 보기 위해 액세스 토큰을 얻기 위한 간단한 수동 단계를 제공합니다.

HTTPS

클라이언트 측 OAuth 2.0 흐름을 시뮬레이션하려면 OAuth 클라이언트 ID 사용자 인증 정보를 URI에 추가한 다음 웹브라우저를 통해 HTTPS 요청을 보냅니다.

  1. 웹브라우저에서 API 사용자 인증 정보의 클라이언트 ID를 사용하여 액세스 토큰을 요청합니다. 다음 예에서는 client_id=[MY_CLIENT_ID] 및 redirect_uri=https://www.google.com을 사용합니다. 여기서 [MY_CLIENT_ID]는 이전에 만든 사용자 인증 정보의 클라이언트 ID입니다.

    https://accounts.google.com/o/oauth2/v2/auth?response_type=token&client_id=[MY_CLIENT_ID]&scope=https://www.googleapis.com/auth/cloud-platform&redirect_uri=https://www.google.com

  2. 요청 응답에서 액세스 토큰을 검색합니다.

    웹브라우저의 주소 필드에는 사용자 인증 정보에 지정한 리디렉션 URI와 URI에 추가된 액세스 토큰이 포함되어야 합니다. 예를 들면 다음과 같습니다.

    https://www.google.com/#access_token=[MY_ACCESS_TOKEN]&token_type=Bearer&expires_in=3600

    이제 access_token 필드에 제공된 액세스 토큰 [MY_ACCESS_TOKEN]을 사용하여 Google Cloud 프로젝트에 HTTP 요청을 보낼 수 있습니다.

gcloud

액세스 토큰을 간단하게 검색하려면 다음 gcloud 명령어를 실행합니다.

  1. 액세스 토큰 요청에 사용하려는 ADC(애플리케이션 기본 사용자 인증 정보)를 설정합니다.

    gcloud auth application-default login

  2. 액세스 토큰을 요청합니다.

    gcloud auth application-default print-access-token

이러한 명령어에 대한 자세한 내용은 gcloud auth application-default를 참조하세요.

주의: 액세스 토큰은 발급되고 약 60분 후에 만료됩니다.

위 옵션은 프로그래매틱 방식 구현용이 아니지만 OAuth 2.0 승인 흐름을 구현하는 방법에 대한 정보는 Admin API 액세스에 나와 있습니다.

Hello World 앱 배포

Admin API에서 HTTP 요청을 사용하여 Hello World 앱을 배포합니다.

  1. Admin API를 사용하여 HTTP POST 요청을 보내는 방법으로 Hello World 앱 버전을 App Engine 애플리케이션에 배포합니다. 예를 들면 다음과 같습니다. 

    POST https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions app.json

    cURL 명령어 예:

    app.json 구성 파일을 만든 디렉터리에서 명령어를 실행합니다. 예를 들면 다음과 같습니다.

    cd root/python-docs-samples/appengine/standard/hello_world/

curl -X POST -T "app.json" -H "Content-Type: application/json" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions

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

    • [MY_ACCESS_TOKEN]은 HTTP 요청을 승인하기 위해 받은 액세스 토큰입니다.
    • [MY_PROJECT_ID]는 버전을 배포하려는 프로젝트의 ID입니다.

    응답 예:

    {
  "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "insertTime": "2016-07-29T17:12:44.679Z",
    "method": "google.appengine.v1.Versions.CreateVersion",
    "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
    "user": "me@example.com"
  }
}

    여기서 [MY_PROJECT_ID]는 Google Cloud 프로젝트 ID입니다.

  2. Hello World 앱 버전이 App Engine 애플리케이션에 배포되었는지 확인합니다.

    1. HTTP GET 메서드에서는 이전 단계에서 반환된 작업 이름을 name 필드로 사용하여 실제 배포 작업의 상태를 확인합니다. 예를 들면 다음과 같습니다.

      GET https://appengine.googleapis.com/v1/[OPERATION_NAME]

      cURL 명령어 예:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/[OPERATION_NAME]

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

      • [OPERATION_NAME]은 앱을 배포할 때 이전 단계에서 반환된 name 필드의 값입니다(예: apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85).
      • [MY_ACCESS_TOKEN]은 HTTP 요청을 승인하기 위해 받은 액세스 토큰입니다.
      • [MY_PROJECT_ID]는 버전을 배포하려는 프로젝트의 ID입니다.

      응답 예:

      {
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "endTime": "2016-07-29T17:13:20.424Z",
    "insertTime": "2016-07-29T17:12:44.679Z",
    "method": "google.appengine.v1.Versions.CreateVersion",
    "target": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
    "user": "me@example.com"
  },
  "name": "apps/[MY_PROJECT_ID]/operations/89729825-ef1f-4ffa-b3e3-e2c25eb66a85",
  "response": {
    "@type": "type.googleapis.com/google.appengine.v1.Version",
    "creationTime": "2016-07-29T17:12:46.000Z",
    "deployer": "me@example.com",
    "id": "appengine-helloworld",
    "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
    "runtime": "python27",
    "servingStatus": "SERVING",
    "threadsafe": true,
  }
}

      여기서 [MY_PROJECT_ID]는 Google Cloud 프로젝트 ID입니다.

    2. HTTP GET 요청을 사용하여 버전 세부정보를 확인하는 방법으로 Hello World 앱 버전이 App Engine 애플리케이션에 생성되었는지 확인합니다. 예를 들면 다음과 같습니다.

      GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL

      cURL 명령어 예:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld/?view=FULL

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

      • [MY_ACCESS_TOKEN]은 HTTP 요청을 승인하기 위해 받은 액세스 토큰입니다.
      • [MY_PROJECT_ID]는 버전을 배포하려는 프로젝트의 ID입니다.

      응답 예:

      {
  "creationTime": "2016-07-29T17:12:46.000Z",
  "deployer": "me@example.com",
  "deployment": {
    "files": {
      "main.py": {
        "sha1Sum": "13f7ea1e24f7cd2de5c66660525f2b509da37c14",
        "sourceUrl": "https://storage.googleapis.com/admin-api-public-samples/hello_world/main.py"
      }
    }
  },
  "handlers": [
    {
      "authFailAction": "AUTH_FAIL_ACTION_REDIRECT",
      "login": "LOGIN_OPTIONAL",
      "script": {
        "scriptPath": "main.app",
      },
      "securityLevel": "SECURE_OPTIONAL",
      "urlRegex": "/.*"
    }
  ]
  "id": "appengine-helloworld",
  "name": "apps/[MY_PROJECT_ID]/services/default/versions/appengine-helloworld",
  "runtime": "python27",
  "servingStatus": "SERVING",
  "threadsafe": true,
  "versionUrl": "https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot"
}

      여기서 [MY_PROJECT_ID]는 Google Cloud 프로젝트 ID입니다.

  3. 이전 단계의 HTTP 응답에서 versionUrl 필드에 지정된 URL을 방문하여 웹브라우저에서 Hello World 앱을 확인합니다. 예를 들면 다음과 같습니다.

    https://appengine-helloworld-dot-[MY_PROJECT_ID].[REGION_ID].r.appspot.com

    여기서 [MY_PROJECT_ID]는 Google Cloud 프로젝트 ID입니다.

    REGION_ID는 앱을 만들 때 선택한 리전을 기준으로 Google에서 할당하는 축약된 코드입니다. 일부 리전 ID는 일반적으로 사용되는 국가 및 주/도 코드와 비슷하게 표시될 수 있지만 코드는 국가 또는 주/도와 일치하지 않습니다. 2020년 2월 이후에 생성된 앱의 경우 REGION_ID.r이 App Engine URL에 포함됩니다. 이 날짜 이전에 만든 기존 앱의 경우 URL에서 리전 ID는 선택사항입니다.

  4. Hello World 앱에 대한 트래픽을 구성합니다.

    기본적으로, 새로운 App Engine 애플리케이션에 배포하는 초기 버전은 자동으로 트래픽을 100% 수신하며 모든 후속 버전은 트래픽을 전혀 수신하지 않습니다.

    1. 현재 버전이 트래픽을 수신하도록 구성되어 있는지 확인하려면 HTTP GET 요청을 보냅니다. 예를 들면 다음과 같습니다.

      GET https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

      cURL 명령어 예:

      curl -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default

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

      • [MY_ACCESS_TOKEN]은 HTTP 요청을 승인하기 위해 받은 액세스 토큰입니다.
      • [MY_PROJECT_ID]는 버전을 배포하려는 프로젝트의 ID입니다.

      응답 예:

      {
  "name": "apps/[MY_PROJECT_ID]/services/default/",
  "id": "default",
  "split": {
    "allocations": {
      "appengine-helloworld": 1
    }
  }
}

      여기서 [MY_PROJECT_ID]는 Google Cloud 프로젝트 ID입니다.

    2. 모든 트래픽을 한 버전으로 옮기려면 HTTP PATCH 요청을 보냅니다. 예를 들면 다음과 같습니다.

      PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split {"split": { "allocations": { "appengine-helloworld": 1 } } }

      cURL 명령어 예:

      curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'allocations': { 'appengine-helloworld': '1' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split

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

      • [MY_ACCESS_TOKEN]은 HTTP 요청을 승인하기 위해 받은 액세스 토큰입니다.
      • [MY_PROJECT_ID]는 버전을 배포하려는 프로젝트의 ID입니다.

      응답 예:

      {
  "name": "apps/[MY_PROJECT_ID]/operations/bdda402c-77a9-4c6d-b022-f2f69ba78420",
  "metadata": {
    "@type": "type.googleapis.com/google.appengine.v1.OperationMetadataV1",
    "insertTime": "2016-07-29T17:25:30.413Z",
    "method": "com.google.appengine.v1.Services.UpdateService",
    "target": "apps/[MY_PROJECT_ID]/services/default",
    "user": "me@example.com"
  }
}

      여기서 [MY_PROJECT_ID]는 Google Cloud 프로젝트 ID입니다.

추가 학습

앱 버전이 두 개 이상 있는 경우 다음 단계를 수행하여 해당 버전 간에 트래픽을 분할할 수 있습니다.

  1. Hello World 앱의 두 번째 버전을 동일한 App Engine 애플리케이션에 배포하려면 다음 단계를 따릅니다.

    1. 이전에 만든 Hello World 앱의 기존 app.json 구성 파일에서 id 필드를 업데이트하여 다른 버전을 지정합니다. 예를 들어 -2를 추가합니다.

      "id": "appengine-helloworld-2"

    2. 동일한 단계를 모두 다시 수행하여 appengine-helloworld-2 버전을 배포합니다. 예를 들면 다음과 같습니다.

      1. 프로젝트를 인증합니다.
      2. 새 appengine-helloworld-2 버전을 배포합니다.
      3. appengine-helloworld-2 버전이 성공적으로 배포되었는지 확인합니다.
      4. 웹브라우저에서 실행 중인 앱을 확인합니다.

  2. 트래픽 마이그레이션 및 분할에 나와 있는 트래픽 분할 안내를 따릅니다. 예를 들어 HTTP PATCH 요청을 보냅니다.

    PATCH https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split { 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }

    cURL 명령어 예:

    curl -X PATCH -H "Content-Type: application/json" -d "{ 'split': { 'shardBy': 'IP', 'allocations': { 'appengine-helloworld': '0.5', 'appengine-helloworld-2': '0.5' } } }" -H "Authorization: Bearer [MY_ACCESS_TOKEN]" https://appengine.googleapis.com/v1/apps/[MY_PROJECT_ID]/services/default/?updateMask=split

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

    • [MY_ACCESS_TOKEN]은 HTTP 요청을 승인하기 위해 받은 액세스 토큰입니다.
    • [MY_PROJECT_ID]는 버전을 배포하려는 프로젝트의 ID입니다.

다음 단계

  • 애플리케이션 사용자 인증 정보 생성, 구성, 설정: API 액세스