app.yaml 참조

app.yaml 파일에서 App Engine 앱 설정을 구성할 수 있습니다. 이 파일은 URL 경로가 요청 핸들러와 정적 파일에 대응하는 방식을 지정합니다. 또한 app.yaml 파일에는 애플리케이션 ID 및 최신 버전의 식별자와 같은 앱 코드에 관한 정보도 포함되어 있습니다.

개별 app.yaml 파일은 앱에서 개별 서비스의 배포를 위한 설명어 역할을 합니다. 앱 내 추가 서비스를 위해 app.yaml 파일을 만들고 배포하려면 먼저 default 서비스에 대한 app.yaml 파일을 만들어야 합니다.

서비스의 app.yaml 파일은 해당 서비스의 루트 디렉토리에 있어야 합니다. 앱에서 여러 서비스를 구성하는 방법은 구성 파일을 참조하세요.

다음은 Python 애플리케이션의 app.yaml 파일 예시입니다.

runtime: python27
api_version: 1
threadsafe: true

handlers:
- url: /
  script: home.app

- url: /index\.html
  script: home.app

- url: /stylesheets
  static_dir: stylesheets

- url: /(.*\.(gif|png|jpg))$
  static_files: static/\1
  upload: static/.*\.(gif|png|jpg)$

- url: /admin/.*
  script: admin.app
  login: admin

- url: /.*
  script: not_found.app

script: 지시어가 .py로 끝나는 파일 경로를 포함하는 경우 스크립트가 CGI를 사용한다는 의미이며, 점으로 구분된 패키지 이름이 있는 Python 모듈 경로를 포함하는 경우 스크립트가 WSGI를 사용한다는 의미입니다.

구문

app.yaml 구문은 YAML 형식입니다.

YAML 형식에서는 주석이 지원됩니다. 우물 정자(#)로 시작하는 줄은 무시됩니다.

# This is a comment.

URL과 파일 경로 패턴은 대조 요소와 대조 클래스를 제외한 POSIX 확장 정규 표현식 구문을 사용합니다. 그룹화된 일치 항목(예: \1)에 대한 역참조가 지원되며 \w \W \s \S \d \D와 같은 PERL 확장도 지원됩니다.

런타임 및 앱 요소

요소 설명
application

app.yaml 파일에서 application 요소를 삭제하고 대신 명령줄 플래그를 사용하여 애플리케이션 ID를 지정하는 것이 좋습니다.

  • gcloud app deploy 명령어를 사용하려면 --project 플래그를 지정해야 합니다.
    
    gcloud app deploy --project [YOUR_PROJECT_ID]
  • appcfg.py update 명령어를 사용하려면 -A 플래그를 지정해야 합니다.
    
    appcfg.py update -A [YOUR_PROJECT_ID]

명령어 사용에 관한 자세한 내용은 앱 배포를 참조하세요.

애플리케이션 ID는 Google Cloud Platform 콘솔에서 애플리케이션을 만들 때 지정한 GCP 콘솔 프로젝트 ID입니다.

api_version

필수. 앱에서 사용하는 특정 런타임 환경의 API 버전입니다.

Google에서 새로운 버전의 런타임 환경 API 지원이 발표되더라도, 이전에 배포된 앱에는 해당 앱을 작성하는 데 사용된 API 버전이 계속 사용됩니다. 앱을 새로운 API 버전으로 업그레이드하려면 이 값을 변경한 후 앱을 App Engine에 다시 배포해야 합니다. 1 값을 지정하면 앱을 배포할 때마다 지원되는 최신 런타임 환경이 사용됩니다(현재는 ).

현재까지 App Engine의 python 런타임 환경 버전은 1 하나만 있습니다.

auto_id_policy 선택사항. 항목 식별자를 자동으로 설정하는 경우, 자동 ID 정책을 설정하여 사용되는 방법을 변경할 수 있습니다. 유효한 옵션은 다음과 같습니다.
default
기본값. 64비트 부동 소수점으로 표시할 수 있을 만큼 작고 잘 분포된 큰 정수인 분산형 자동 ID를 사용합니다.
legacy
이전 옵션은 이후 출시 버전에서 지원 중단되고 결국 삭제될 예정입니다. 자세한 내용은 이 변경 사항을 알리는 블로그 글을 참조하세요.
builtins

선택사항. Python SDK에는 일반적인 애플리케이션 기능을 위한 여러 핸들러가 내장되어 있습니다. builtins 지시어를 사용하면 app.yaml에 특정 핸들러를 포함할 수 있습니다.

사용할 수 있는 내장 핸들러는 다음과 같습니다.

appstats
/_ah/stats/에서 Appstats를 사용 설정하며 이를 통해 애플리케이션 성능을 측정할 수 있습니다. Appstats를 사용하려면 이벤트 레코더를 설치해야 합니다.
deferred
/_ah/queue/deferred에서 지연 핸들러를 사용 설정합니다. 이 내장 기능을 통해 개발자는 deferred.defer()를 사용하여 작업 대기열 작업을 간단하게 생성할 수 있습니다. 지연된 라이브러리를 이용한 백그라운드 작업을 참조하세요.
remote_api
/_ah/remote_api/에서 remote_api 내장 기능을 사용 설정합니다. 이 내장 기능을 사용하면 올바른 사용자 인증 정보가 있는 원격 애플리케이션이 데이터 저장소에 원격으로 액세스할 수 있습니다.
예:

builtins:
- deferred: on
- appstats: on

builtins 지시어는 includes 지시어의 특별 인스턴스입니다. Python에서 각 builtin 지시어는 확장된 경로가 있는 includes 지시어와 같습니다. 예:


builtins:
- name: on

위 항목은 다음과 동일합니다.


includes:
- $PYTHON_LIB/google/appengine/ext/builtins/name/

app.yaml 파일에 builtins를 사용하는 경우 내장된 include.yaml 파일에 정의된 모든 핸들러는 app.yaml 파일에 정의된 핸들러를 대체합니다. 그러나 builtins 또는 includes를 사용하는 파일을 포함하면 핸들러는 include 계층 구조의 순서대로 추가됩니다. 즉 '상위' include의 핸들러는 '하위' include의 내장 기능 이전에 추가되는 식으로 작업이 수행됩니다.

다음과 같이 appstats 내장 핸들러를 사용하는 app.yaml을 예로 들어 보겠습니다.


handlers:
- url: /.*
  script: main.app
builtins:
- appstats: on

핸들러의 결과 목록은 다음과 같습니다.


[/_ah/stats, /.*]

app.yaml이 includes 지시어를 사용하는 경우,


includes:
- included.yaml

그리고 included.yaml 파일이 builtins를 사용하는 경우,


handlers:
- url: /.*
  script: main.app
builtins:
- appstats: on

핸들러의 결과 목록은 다음과 같습니다.


[/.*, /_ah/stats]

.yaml 파일에서 builtins 절의 배치 순서는 동작을 변경하지 않습니다.

default_expiration

선택사항. 애플리케이션의 모든 정적 파일 핸들러에 대한 전역 기본 캐시 기간을 설정합니다. 또한 특정 정적 파일 핸들러의 캐시 기간을 구성할 수도 있습니다. 값은 공백으로 구분된 숫자와 단위 문자열입니다. 단위는 d(일), h(시간), m(분), s(초)일 수 있습니다. 예를 들어 "4d 5h"는 파일이 처음 요청되고 나서 4일 5시간 후로 캐시 만료를 설정합니다. 생략하면 프로덕션 서버가 만료 시간을 10분으로 설정합니다.

예:

runtime: python27
api_version: 1
threadsafe: true

default_expiration: "4d 5h"

handlers:
# ...

자세한 내용은 정적 캐시 만료를 참조하세요.

env_variables

선택사항. 앱에 사용할 수 있도록 app.yaml 파일에서 환경 변수를 정의할 수 있습니다.

GAE로 시작하는 환경 변수는 시스템용으로 예약되어 있으며 app.yaml 파일에서 허용되지 않습니다.

이러한 변수는 os.environ 사전에서 확인할 수 있습니다.

env_variables:
  DJANGO_SETTINGS_MODULE: 'myapp.settings'
error_handlers

선택사항. 오류 유형에 따라 반환되는 커스텀 오류 페이지를 구성하는 데 사용됩니다.

이 요소에는 다음 요소가 포함될 수 있습니다.

error_code
선택사항. error_code는 다음 중 하나일 수 있습니다.
over_quota
앱이 리소스 할당량을 초과했음을 나타냅니다.
dos_api_denial
요청이 앱의 DoS 보호 구성에 의해 차단되었음을 나타냅니다.
timeout
앱에서 응답하기 전에 기한이 도달한 경우에 제공됩니다.

error_code는 선택사항입니다. 지정하지 않으면 제공된 파일이 앱의 기본 오류 응답이 됩니다.

file
각 파일 항목은 일반 오류 응답을 대신하여 제공되어야 하는 정적 파일을 나타냅니다. 해당하는 error_code 요소 없이 file 요소를 지정할 경우 정적 파일이 앱의 기본 오류 페이지가 됩니다. 커스텀 오류 데이터는 10KB 미만이어야 합니다.

error_handlers:
  - file: default_error.html

  - error_code: over_quota
    file: over_quota.html
handlers

필수. URL 패턴과 그 처리 방법에 대한 설명이 포함된 목록입니다. App Engine은 애플리케이션 코드를 실행하거나 이미지, CSS 또는 자바스크립트와 같이 코드와 함께 업로드된 정적 파일을 제공하여 URL을 처리할 수 있습니다.

핸들러 및 하위 요소 구문 참조

includes

선택사항. includes 지시어를 사용하면 애플리케이션 전반에서 모든 라이브러리 또는 서비스용 구성 파일을 포함할 수 있습니다. 예를 들어, 다음과 같이 사용자 관리 라이브러리를 포함할 수 있습니다.


includes:
- lib/user_admin.yaml

App Engine은 포함된 경로를 다음 순서로 확인합니다.

  • 작업 디렉토리의 절대 경로 또는 상대 경로. 지정된 경로는 파일을 확인합니다.
  • 기본 경로라고도 하는 애플리케이션 디렉토리에 상대되는 경로. 기본 경로와 경로는 파일을 확인합니다.
  • 현재 파일을 포함한 파일에 상대되는 경로. 참조 파일의 위치와 포함 경로는 포함된 파일을 확인합니다.

include 지시어가 디렉토리를 지정하면 App Engine이 해당 디렉토리에서 include.yaml이라는 파일을 찾습니다. include 지시어가 파일인 경우, 해당 특정 파일이 포함됩니다. includes를 사용하면 대상 파일(존재할 경우)에서 다음과 같은 지시어 유형만 검색합니다.

skip_files 패턴을 포함하면 포함된 app.yaml의 패턴에 추가되거나 app.yaml에 목록이 명시되어 있지 않은 경우 기본 목록에 추가됩니다. skip_files는 절대 경로를 비교한다는 점에 유의하세요.

inbound_services

선택사항. 애플리케이션이 이메일을 수신할 수 있으려면 해당 서비스를 사용 설정하도록 애플리케이션을 구성해야 합니다. app.yaml 파일에 inbound_services 섹션을 포함하여 Python 앱에 대한 서비스를 사용 설정하세요.

다음과 같은 인바운드 서비스를 사용할 수 있습니다.

mail
애플리케이션이 메일을 수신하도록 허용합니다.
warmup
준비 요청을 사용 설정합니다. 준비 요청 구성을 참조하세요.
예:

inbound_services:
  - mail
  - warmup
instance_class

선택사항. 이 서비스의 인스턴스 클래스입니다.

서비스 확장에 따라 다음 값을 사용할 수 있습니다.

자동 확장
F1, F2, F4, F4_1G
기본값: automatic_scaling 요소와 함께 인스턴스 클래스를 지정하지 않으면 F1이 할당됩니다.
기본 및 수동 확장
B1, B2, B4, B4_1G, B8
기본값: basic_scaling 요소 또는 manual_scaling 요소와 함께 인스턴스 클래스를 지정하지 않으면 B2가 할당됩니다.

참고: instance_classF2 이상으로 설정된 경우 max_concurrent_requests를 기본값인 10보다 큰 값으로 설정하여 인스턴스를 최적화할 수 있습니다. 최적 값을 찾으려면 값을 점차적으로 높이면서 애플리케이션 성능을 모니터링하세요.

libraries

선택사항. Python 2.7 런타임에는 타사 라이브러리가 포함되어 있습니다. 이 중 일부는 기본적으로 사용할 수 있으며 그 외에는 구성된 경우에만 사용할 수 있습니다. nameversion 값을 지정하여 사용할 버전을 지정할 수 있습니다.


libraries:
- name: PIL
  version: "1.1.7"
- name: webob
  version: "latest"
        

latest를 지정하면 SDK는 배포 시 최신 라이브러리 버전을 결정합니다. 일단 배포되면 라이브러리 버전은 변경되지 않습니다. 다른 버전의 라이브러리를 사용하는 유일한 방법은 다시 배포하는 것입니다.

아직 사용자가 없는 애플리케이션을 개발 중인 경우 새로운 버전을 추적할 필요가 없습니다. 그러나 애플리케이션이 활발히 사용되는 경우 애플리케이션이 이전 버전과 호환되지 않는 새로운 라이브러리 버전을 사용할 수 있으므로 주의하시기 바랍니다.

포함된 타사 라이브러리 목록은 타사 라이브러리를 참조하세요. 로컬 디렉토리에 설치하여 순수 Python 타사 라이브러리를 추가로 사용할 수 있습니다.

가변형 환경을 사용하는 경우 가변형 환경에서 Python 라이브러리 사용하기를 참조하세요.

module

참고: 이제는 모듈을 서비스라고 합니다.

gcloud 도구로 앱을 관리하려면, 서비스 요소를 대신 사용하세요.

appcfg 도구를 사용하려면 app.yaml 파일에 서비스가 모듈로 선언되어 있어야 합니다. 예:


module: service-name

서비스를 만들 경우 필수 항목입니다. default 서비스의 경우에는 선택사항입니다. 각 서비스와 버전에는 이름이 있어야 합니다. 이름에는 숫자, 문자, 하이픈을 포함할 수 있습니다. 63자(영문 기준)를 초과할 수 없으며 하이픈으로 시작하거나 끝날 수 없습니다. 각 서비스와 버전에 고유한 이름을 선택하세요. 서비스와 버전 간에 이름을 재사용하지 마세요.

runtime

필수. 앱에서 사용되는 런타임 환경 이름입니다. Python을 지정하려면 python을 사용합니다.


runtime: python
service

서비스는 이전에 모듈이라고 불렸습니다.

gcloud 도구 또는 Cloud SDK 기반 플러그인에서만 지원됩니다. 예: gcloud app deploy.

appcfg 도구를 사용하려면 모듈을 참조하세요.

서비스를 만들 경우 필수 항목입니다. default 서비스의 경우에는 선택사항입니다. 각 서비스와 버전에는 이름이 있어야 합니다. 이름에는 숫자, 문자, 하이픈을 포함할 수 있습니다. 63자(영문 기준)를 초과할 수 없으며 하이픈으로 시작하거나 끝날 수 없습니다. 각 서비스와 버전에 고유한 이름을 선택하세요. 서비스와 버전 간에 이름을 재사용하지 마세요.

예:

service: service_name

참고: gcloud app deploy 명령어는 이전 버전과 호환되며 모듈로 선언된 서비스를 포함하는 기존 app.yaml 파일을 지원합니다. 예:


module: service_name
skip_files

선택사항. skip_files 요소는 애플리케이션 디렉토리에서 App Engine에 업로드하지 않을 파일을 지정합니다. 이 값은 정규 표현식이거나 정규 표현식 목록입니다. 정규 표현식과 일치하는 파일 이름은 애플리케이션을 업로드할 때 업로드할 파일 목록에서 생략됩니다. 파일 이름은 프로젝트 디렉토리를 기준으로 합니다.

skip_files의 기본값은 다음과 같습니다.


skip_files:
- ^(.*/)?#.*#$
- ^(.*/)?.*~$
- ^(.*/)?.*\.py[co]$
- ^(.*/)?.*/RCS/.*$
- ^(.*/)?\..*$

이름의 형식이 #...#, ...~인 Emacs 백업 파일, .pyc.pyo 파일, RCS 버전 관리 디렉토리의 파일, 이름이 점(.)으로 시작하는 Unix 숨김 파일은 기본 패턴에서 제외됩니다.

위의 정규 표현식 목록을 확장하려면 위의 목록을 복사하여 app.yaml에 붙여넣고 사용자의 고유한 정규 표현식을 추가합니다. 예를 들어, 기본 패턴 외에 이름이 .bak로 끝나는 파일을 건너뛰려면 skip_files에 다음과 같은 항목을 추가합니다.


skip_files:
- ^(.*/)?#.*#$
- ^(.*/)?.*~$
- ^(.*/)?.*\.py[co]$
- ^(.*/)?.*/RCS/.*$
- ^(.*/)?\..*$
- ^(.*/)?.*\.bak$

전체 디렉토리를 건너뛰려면 목록에 디렉토리 이름을 추가합니다. 예를 들어, logs라는 이름의 디렉토리를 건너뛰려면 앞에서 설명한 코드에 다음 줄을 추가합니다.


skip_files:
- logs/
threadsafe

필수. 동시 요청을 사용하도록 애플리케이션을 구성합니다. Python의 스레딩 라이브러리를 사용하는 경우 threading.local()에 의해 반환된 스레드 로컬 데이터는 각 요청 이후 삭제됩니다.


threadsafe: [true | false]

참고: threadsafe 지시어는 Python 애플리케이션에 필요합니다. threadsafe: true가 되려면 모든 스크립트 핸들러가 WSGI 핸들러여야 합니다. 즉, 각 스크립트는 점으로 구분된 패키지 이름과 Python 모듈 경로를 사용하여 script: 지시어에 지정되어야 합니다. Python 모듈 경로를 사용하는 script: 지시어의 마지막 구성요소는 service:의 전역 변수 이름으로, 해당 변수는 WSGI 앱이어야 하며 보통 규칙에 따라 app으로 불립니다.

version

app.yaml 파일에서 version 요소를 삭제하고 대신 명령줄 플래그를 사용하여 버전 ID를 지정하는 것이 좋습니다.

  • gcloud app deploy 명령어를 사용하려면 -v 플래그를 지정합니다.
    
    gcloud app deploy -v [YOUR_VERSION_ID]
  • appcfg.py update 명령어를 사용하려면 -V 플래그를 지정합니다.
    
    appcfg.py update -V [YOUR_VERSION_ID]

명령어 사용에 관한 자세한 내용은 앱 배포를 참조하세요.

App Engine에 배포하는 애플리케이션 코드의 버전을 위한 식별자입니다.

버전 ID는 소문자, 숫자, 하이픈을 포함할 수 있습니다. 프리픽스 ah-로 시작할 수 없으며 defaultlatest라는 이름은 예약되어 있어서 사용할 수 없습니다.

참고: 항상 숫자로 지정되는 숫자 인스턴스와 구분하기 위해, 버전 이름은 문자로 시작해야 합니다. 이를 통해 123.my-service.appspot.com과 같이 두 가지로 해석될 수 있는 URL의 모호성을 방지할 수 있습니다. 이 경우에는 버전 '123'이 존재하면 대상은 지정된 서비스의 버전 '123'이 됩니다. 버전이 존재하지 않는다면 대상은 기본 서비스 버전의 123번 인스턴스가 될 것입니다.

애플리케이션의 각 버전에는 app.yaml의 고유 복사본이 포함됩니다. 애플리케이션이 업로드될 때는 업로드되는 app.yaml 파일에 언급된 버전이 해당 업로드 작업으로 생성 또는 교체됩니다. 관리자는 Google Cloud Platform 콘솔을 사용하여 트래픽을 처리하는 데 사용되는 애플리케이션 버전을 변경할 수 있으며, 이러한 버전이 트래픽을 수신하도록 구성하기 전에 다른 버전을 테스트할 수도 있습니다.

핸들러 요소

handlers 요소는 app.yaml에서 필수 요소입니다. 이 요소는 URL 패턴과 그 처리 방법에 대한 설명이 포함된 목록을 제공합니다. App Engine은 애플리케이션 코드를 실행하거나 이미지, CSS 또는 자바스크립트와 같이 코드와 함께 업로드된 정적 파일을 제공하여 URL을 처리할 수 있습니다.

패턴은 app.yaml 파일에 표시된 순서에 따라 위에서 아래로 평가됩니다. 패턴이 URL과 일치하는 첫 번째 매핑이 요청 처리를 위해 사용됩니다.

다음 표에는 스크립트, 정적 파일, 정적 디렉토리, 기타 설정의 동작을 제어하는 handlers 요소의 하위 요소가 나열되어 있습니다.

요소 설명
application_readable 선택사항. 부울. 기본적으로 정적 파일 핸들러에 선언된 파일은 정적 데이터로 업로드되며 최종 사용자에게만 제공됩니다. 애플리케이션은 이러한 파일을 읽을 수 없습니다. 이 필드를 true로 설정할 경우, 애플리케이션이 파일을 읽을 수 있도록 해당 파일이 코드 데이터로도 업로드됩니다. 두 가지 업로드 모두 사용자 코드 및 정적 데이터 저장소 리소스 할당량에 따라 청구됩니다.
auth_fail_action

선택사항. login 요소가 핸들러에 지정되었고 사용자가 로그인되지 않았을 때 수행되는 작업을 설명합니다. 다음 두 가지 값을 지정할 수 있습니다.

redirect
기본값. 사용자가 Google 로그인 페이지 또는 /_ah/login_required(OpenID 인증이 사용된 경우)로 리디렉션됩니다. 사용자가 로그인하거나 계정을 만든 후에는 다시 애플리케이션 URL로 리디렉션됩니다.
unauthorized
요청이 거부되고 HTTP 401 상태 코드와 오류 메시지가 표시됩니다.

애플리케이션에 다른 동작이 필요한 경우 애플리케이션 자체가 사용자 로그인 처리를 구현할 수 있습니다. 자세한 내용은 Users API를 참조하세요.

다음 예에서는 /profile/ 디렉토리의 경우 일반 로그인이 필요하고, /admin/ 디렉토리의 경우 관리자 로그인이 필요합니다.


handlers:
- url: /profile/.*
  script: user_profile.app
  login: required

- url: /admin/.*
  script: admin.app
  login: admin

- url: /.*
  script: welcome.app

핸들러 구성에 auth_fail_action: unauthorized를 추가하면 사용자가 로그인되지 않았을 때 사용자를 로그인 페이지로 리디렉션하는 대신 보호된 URL에 대한 액세스를 거부하도록 핸들러를 구성할 수 있습니다.


handlers:
- url: /secure_api/.*
  script: api_handler.app
  login: required
  auth_fail_action: unauthorized
expiration 선택사항. 이 핸들러에서 제공한 정적 파일을 웹 프록시 및 브라우저가 캐시해야 하는 시간입니다. 값은 공백으로 구분된 숫자와 단위 문자열입니다. 단위는 d(일), h(시간), m(분), s(초)일 수 있습니다. 예를 들어 "4d 5h"는 파일이 처음 요청되고 나서 4일 5시간 후로 캐시 만료를 설정합니다. 생략하면 애플리케이션의 default_expiration이 사용됩니다. 자세한 내용은 정적 캐시 만료를 참조하세요.
http_headers

선택사항. 정적 파일 또는 디렉토리 핸들러의 응답에 HTTP 헤더를 설정할 수 있습니다. script 핸들러에서 HTTP 헤더를 설정해야 하는 경우 앱의 코드에서 대신 설정하는 것이 좋습니다.


handlers:
- url: /images
  static_dir: static/images
  http_headers:
    X-Foo-Header: foo
    X-Bar-Header: bar value

CORS 지원

이 기능의 중요한 용도 중 하나는 다른 App Engine 앱에서 호스팅하는 파일에 대한 액세스와 같은 CORS(교차 출처 리소스 공유)를 지원하는 것입니다.

예를 들어 mygame.appspot.com이 호스팅하는 애셋에 액세스하는 게임 앱 myassets.appspot.com이 있다고 가정해 보겠습니다. 하지만 mygame이 자바스크립트 XMLHttpRequest 요청을 myassets에 전송하려고 시도할 때, myassets의 핸들러가 http://mygame.appspot.com 값이 포함된 Access-Control-Allow-Origin: 응답 헤더를 반환하지 않는 한, 작업이 성공하지 않습니다.

정적 파일 핸들러가 필요한 응답 헤더 값을 반환하도록 만드는 방법은 다음과 같습니다.


handlers:
- url: /images
  static_dir: static/images
  http_headers:
    Access-Control-Allow-Origin: http://mygame.appspot.com

참고: 모든 사람이 애셋에 액세스하도록 허용하려면 http://mygame.appspot.com 대신 와일드 카드 '*'을 사용하면 됩니다.

login

선택사항. URL 핸들러가 사용자의 로그인을 요구할지 여부를 결정합니다. 이 요소에 가능한 세 가지 값은 다음과 같습니다.

optional
기본값. 사용자의 로그인을 요구하지 않습니다.
required
사용자가 로그인되었으면 핸들러가 정상적으로 진행됩니다. 그렇지 않으면 auth_fail_action에 지정된 작업이 수행됩니다.
admin
required와 마찬가지로, 사용자가 로그인되지 않았으면 auth_fail_action을 수행합니다. 또한 사용자가 애플리케이션의 관리자가 아니면 auth_fail_action 설정에 관계없이 오류 메시지가 표시됩니다. 사용자가 관리자면 핸들러가 진행됩니다.

optional 이외의 login 설정을 포함하는 URL 핸들러가 특정 URL과 일치한다면 핸들러는 먼저 해당 인증 옵션을 사용해서 사용자가 애플리케이션에 로그인되었는지 여부를 확인합니다. 그렇지 않으면 기본적으로 사용자가 로그인 페이지로 리디렉션됩니다. 또한 사용자를 로그인 페이지로 리디렉션하는 대신 auth_fail_action을 사용해서 올바르게 인증되지 않은 사용자의 핸들러 요청이 단순히 거부되도록 앱을 구성할 수 있습니다.

참고: App Engine이 적절한 X-Appengine 특수 헤더를 설정하는 내부 요청의 경우에도 admin 로그인 제한이 충족됩니다. 예를 들어, cron 예약 작업은 App Engine이 해당 요청에 HTTP 헤더 X-AppEngine-Cron: true를 설정하기 때문에 admin 제한을 충족합니다. 하지만 크론 예약 작업이 어떤 사용자로도 실행되지 않기 때문에 요청은 required 로그인 제한을 충족하지 않습니다.

mime_type

선택사항. 이 값을 지정하면 이 핸들러로 제공되는 모든 파일은 지정된 MIME 유형을 사용하여 제공됩니다. 지정하지 않으면 파일의 MIME 유형이 파일의 파일 이름 확장자로부터 파생됩니다.

가능한 MIME 미디어 유형에 대한 자세한 내용은 IANA MIME 미디어 유형 웹사이트를 참조하세요.

redirect_http_response_code

선택사항. redirect_http_response_codesecure 설정과 함께 secure 설정의 구성 방식에 따라 필요한 리디렉션을 수행할 때 반환되는 HTTP 응답 코드를 설정하기 위해 사용됩니다. redirect_http_response_code 요소에 사용 가능한 값은 다음과 같습니다.

301
응답 코드가 영구적으로 이동되었습니다.
302
응답 코드를 찾았습니다.
303
기타 응답 코드를 참조합니다.
307
응답 코드를 일시적으로 리디렉션합니다.

handlers:
- url: /youraccount/.*
  script: accounts.app
  login: required
  secure: always
  redirect_http_response_code: 301

사용자 요청이 리디렉션되면 HTTP 상태 코드가 redirect_http_response_code 매개변수 값으로 설정됩니다. 매개변수가 없으면 302가 반환됩니다.

script

선택사항. 애플리케이션 루트 디렉토리에서 스크립트로의 경로를 지정합니다.


handlers:
# The root URL (/) is handled by the WSGI application named
# "app" in home.py. No other URLs match this pattern.
- url: /
  script: home.app

# The URL /index.html is also handled by the home.py script.
- url: /index\.html
  script: home.app

# A regular expression can map parts of the URL to the
# path of the script.
- url: /browse/(books|videos|tools)
  script: \1.catalog.app

# All other URLs use the WSGI application named in "app"
# in not_found.py.
- url: /.*
  script: not_found.app

script: 지시어는 Python 가져오기 경로여야 합니다(예: WSGI 애플리케이션을 가리키는 package.module.app). Python 모듈 경로를 사용하는 script: 지시어의 마지막 구성요소는 모듈의 전역 변수 이름으로, 해당 변수는 WSGI 애플리케이션이어야 하며 보통 규칙에 따라 app으로 불립니다.

참고: Python import 구문과 마찬가지로 패키지인 각 하위 디렉토리에는 이름이 __init__.py인 파일이 있어야 합니다.

secure 선택사항. 모든 URL 핸들러는 스크립트 핸들러와 정적 파일 핸들러를 비롯하여 secure 설정을 사용할 수 있습니다. secure 요소에 사용 가능한 값은 다음과 같습니다.
optional
URL이 핸들러와 일치하는 HTTP 및 HTTPS 요청이 모두 리디렉션 없이 성공합니다. 애플리케이션은 요청을 조사하여 사용된 프로토콜을 확인하고 그에 따라 응답할 수 있습니다. 핸들러에 secure가 제공되지 않으면 이것이 기본값입니다.
never
HTTP를 사용하며 이 핸들러와 일치하는 URL 요청은 HTTP에 해당하는 URL로 자동으로 리디렉션됩니다. 사용자의 HTTPS 요청이 HTTP 요청으로 리디렉션되면 요청에서 쿼리 매개변수가 삭제됩니다. 따라서 사용자가 보안 연결로 제출해야 할 쿼리 데이터를 잘못해서 비보안 연결을 통해 제출하지 못하도록 합니다.
always
HTTPS를 사용하지 않으며 이 핸들러와 일치하는 URL 요청은 동일 경로의 HTTPS URL로 자동으로 리디렉션됩니다. 쿼리 매개변수는 리디렉션을 위해 보존됩니다.

handlers:
- url: /youraccount/.*
  script: accounts.app
  login: required
  secure: always

개발 웹 서버는 HTTPS 연결을 지원하지 않습니다. secure 매개변수가 무시되기 때문에 HTTPS에 사용해야 하는 경로를 개발용 웹 서버에 대한 정규 HTTP 연결을 사용하여 테스트할 수 있습니다.

appspot.com 도메인을 사용해서 앱의 특정 버전을 대상으로 지정하려면 일반적으로 URL의 하위 도메인 구성요소를 구분하는 마침표를 '-dot-' 문자열로 바꿉니다. 예:


https://[VERSION_ID]-dot-[YOUR_PROJECT_ID].appspot.com

HTTPS에 커스텀 도메인을 사용하려면 먼저 해당 도메인에 SSL 인증서를 활성화하고 구성해야 합니다.

Google 계정 로그인 및 로그아웃은 애플리케이션의 URL이 구성된 방식과 무관하게 항상 보안 연결을 사용하여 수행됩니다.

static_dir

선택사항. 애플리케이션 루트 디렉토리의 정적 파일을 포함하는 디렉토리 경로입니다. 일치하는 url 패턴 끝 다음에 오는 모든 항목이 static_dir에 추가되어 요청된 파일에 대한 전체 경로를 구성합니다.

디렉토리의 mime_type 설정으로 재정의되지 않는 한 정적 디렉토리의 각 파일은 파일 이름 확장자에 해당하는 MIME 유형을 사용하여 제공됩니다. 제공된 디렉토리의 모든 파일은 정적 파일로 업로드되며 이들 중에서 스크립트로 실행 가능한 것은 없습니다.

이 디렉토리의 모든 파일은 앱과 함께 정적 파일로 업로드됩니다. App Engine은 앱 파일과 별도로 정적 파일을 저장하고 제공합니다. 기본적으로 정적 파일은 앱의 파일 시스템에 제공되지 않습니다. 이를 변경하려면 application_readable 옵션을 true로 설정합니다.

예:

handlers:
# All URLs beginning with /stylesheets are treated as paths to
# static files in the stylesheets/ directory.
- url: /stylesheets
  static_dir: stylesheets
static_files

선택사항. 정적 파일 패턴 핸들러는 URL 패턴을 애플리케이션과 함께 업로드된 정적 파일 경로와 연결합니다. URL 패턴 정규 표현식은 파일 경로를 만들 때 사용할 정규 표현식 그룹화를 정의할 수 있습니다. static_dir 대신 이를 사용해서 전체 디렉토리를 매핑하지 않고도 디렉토리 구조에 포함된 특정 파일로 매핑할 수 있습니다.

예:

handlers:
# All URLs ending in .gif .png or .jpg are treated as paths to
# static files in the static/ directory. The URL pattern is a
# regular expression, with a grouping that is inserted into the
# path to the file.
- url: /(.*\.(gif|png|jpg))$
  static_files: static/\1
  upload: static/.*\.(gif|png|jpg)$

App Engine은 애플리케이션 파일과 별도로 정적 파일을 저장하고 제공합니다. 기본적으로 정적 파일은 애플리케이션의 파일 시스템에 제공되지 않습니다. 이를 변경하려면 application_readable 옵션을 true로 설정합니다.

정적 파일은 애플리케이션 코드 파일과 동일할 수 없습니다. 정적 파일 경로가 동적 핸들러에 사용된 스크립트의 경로와 일치할 경우, 해당 스크립트는 해당 동적 핸들러에 제공되지 않습니다.

upload

선택사항. 이 핸들러에서 참조되는 모든 파일의 파일 경로와 일치하는 정규 표현식입니다. 이 정규 표현식이 필요한 이유는 핸들러가 제공된 urlstatic_files 패턴에 해당하는 애플리케이션 디렉토리 파일을 확인할 수 없기 때문입니다. 정적 파일은 애플리케이션 파일과 별개로 업로드되고 처리됩니다. 위의 [예](#example)에서는 다음 upload 패턴이 사용될 수 있습니다. archives/(.*)/items/(.*)

url

handlers의 경우에는 필수 요소이며 정규 표현식으로 표현되는 URL 패턴입니다. 이 표현식은 스크립트의 파일 경로에서 정규 표현식 역참조를 통해 참조될 수 있는 그룹화를 포함할 수 있습니다. 예를 들어 /profile/(.*)/(.*)는 URL /profile/edit/manager와 일치하고, editmanager를 첫 번째 및 두 번째 그룹화로 사용합니다.

URL 패턴은 다음 요소와 함께 사용될 때 일부 동작이 달라집니다.

static_dir
URL 프리픽스를 사용합니다. 정규 표현식 패턴은 static_dir 요소와 함께 사용할 때 그룹화를 포함하지 않아야 합니다. 이 프리픽스로 시작되는 모든 URL은 이 핸들러에서 프리픽스 다음의 URL 부분을 파일 경로의 일부로 사용하여 처리됩니다.
static_files
정적 파일 패턴 핸들러는 URL 패턴을 애플리케이션과 함께 업로드된 정적 파일 경로와 연결합니다. URL 패턴 정규 표현식은 파일 경로를 만들 때 사용할 정규 표현식 그룹화를 정의할 수 있습니다. static_dir 대신 이를 사용해서 전체 디렉토리를 매핑하지 않고도 디렉토리 구조에 포함된 특정 파일로 매핑할 수 있습니다.

요소 확장

App Engine 앱 확장 방법에 대한 자세한 내용은 동적 인스턴스 확장을 참조하세요.

다음 표에는 애플리케이션의 확장을 지정하는 방법을 정의하기 위한 옵션이 나열되어 있습니다.

요소 설명
automatic_scaling

선택사항. 달리 지정하지 않는 한 기본적으로 자동 확장이 기본 인스턴스 클래스 F1으로 사용됩니다.

automatic_scaling 요소는 서비스의 인스턴스 수, 지연 시간, 동시 연결에 대한 최소 및 최대 수준을 설정합니다.

이 요소에는 다음 요소가 포함될 수 있습니다.

target_cpu_utilization
선택사항. 0.5~0.95 사이의 값을 지정합니다. 기본값은 0.6입니다.

이 매개변수는 트래픽 처리를 위해 새 인스턴스가 시작되는 CPU 사용량 임계값을 지정합니다. 이 요소를 사용하면 성능과 비용 간의 균형을 유지할 수 있습니다. 값을 낮추면 성능과 비용이 높아지고, 값을 높이면 성능이 낮아지지만 비용도 낮아집니다. 예를 들어, 값이 0.7이면 CPU 사용량이 70%에 도달한 후 새 인스턴스가 시작됩니다.

중요: 배포를 위해 Python용 App Engine SDK의 appcfg를 사용할 경우, app.yaml에서 이 매개변수를 사용할 수 없습니다. 대신 API 탐색기에서 자동 확장 매개변수 설정의 설명대로 또는 App Engine Admin API를 사용하여 매개변수를 설정합니다.

target_throughput_utilization
선택사항. 0.5~0.95 사이의 값을 지정합니다. 기본값은 0.6입니다.

동시 요청으로 인해 새 인스턴스가 시작되는 경우를 지정하기 위해 max_concurrent_requests와 함께 사용됩니다. 동시 요청 수가 max_concurrent_requeststarget_throughput_utilization을 곱한 값에 도달하면 스케줄러는 새 인스턴스를 시작합니다.

중요: 배포를 위해 Python용 App Engine SDK의 appcfg를 사용할 경우, app.yaml에서 이 매개변수를 사용할 수 없습니다. 대신 API 탐색기에서 자동 확장 매개변수 설정의 설명대로 또는 App Engine Admin API를 사용하여 매개변수를 설정합니다.

max_instances
선택사항. 0~2147483647 사이의 값을 지정합니다. 0으로 지정하면 설정이 중지됩니다.

이 매개변수는 이 모듈 버전에 대해 만들 수 있는 App Engine의 최대 인스턴스 수를 지정합니다. 이 값은 모듈 비용을 제한하는 데 유용합니다.

중요: 배포를 위해 Python용 App Engine SDK의 appcfg를 사용할 경우, app.yaml에서 이 매개변수를 사용할 수 없습니다. 대신 API 탐색기에서 자동 확장 매개변수 설정의 설명대로 또는 App Engine Admin API를 사용하여 매개변수를 설정합니다.

min_instances
선택사항. 이 모듈 버전에 대해 만들 수 있는 App Engine의 최소 인스턴스 수입니다. 이러한 인스턴스는 요청 도착 시 트래픽을 처리하고 트래픽 처리를 위해 추가 인스턴스가 시작된 경우에도 계속 트래픽을 처리합니다.

0~1000 사이의 값을 지정합니다. 매개변수를 값 0으로 설정하고 인스턴스를 0개로 조정하여 제공된 요청이 없는 경우에 비용을 절감할 수 있습니다. 트래픽 수신 여부에 관계없이 지정된 인스턴스 수에 따라 비용이 청구되니 유의하세요.

중요: 배포를 위해 Python용 App Engine SDK의 appcfg를 사용할 경우, app.yaml에서 이 매개변수를 사용할 수 없습니다. 대신 API 탐색기에서 자동 확장 매개변수 설정의 설명대로 또는 App Engine Admin API를 사용하여 매개변수를 설정합니다.

max_concurrent_requests

선택사항. 스케줄러가 새 인스턴스를 만들기 전에 자동 확장 인스턴스가 수락할 수 있는 동시 요청 수입니다(기본값: 10, 최대값: 80).

동시 요청으로 인해 새 인스턴스가 시작되는 경우를 지정하기 위해 target_throughput_utilization과 함께 사용됩니다. 동시 요청 수가 max_concurrent_requeststarget_throughput_utilization을 곱한 값에 도달하면 스케줄러가 새 인스턴스를 시작합니다.

이 설정이 너무 높으면 API 지연 시간이 늘어날 수 있습니다. 스케줄러는 실제 최대 요청 수에 도달하기 전에 새 인스턴스를 생성할 수 있습니다.

참고: instance_classF2 이상으로 설정되었다면 max_concurrent_requests를 기본값인 10보다 큰 값으로 설정하여 인스턴스를 최적화할 수 있습니다. 최적 값을 찾으려면 값을 점차적으로 높이면서 애플리케이션 성능을 모니터링하세요.

max_idle_instances

이 버전에 App Engine이 유지해야 하는 최대 유휴 인스턴스 수입니다. 기본값은 'automatic'입니다. 다음 사항에 유의하세요.

  • 최대값이 높으면 부하가 급격히 증가한 후 정상 수준으로 돌아올 때 유휴 인스턴스 수가 보다 점진적으로 줄어듭니다. 이렇게 하면 요청 부하가 변동되더라도 성능을 안정적으로 유지하는 데 도움이 되지만 높은 부하 기간 중 유휴 인스턴스 수도 증가(하고 따라서 비용도 증가)합니다.
  • 최대값이 낮으면 실행 비용이 낮아지지만 부하 수준의 변동이 잦은 경우 성능이 저하될 수 있습니다.

참고: 부하 급증 후 정상 수준으로 다시 조정될 때는 유휴 인스턴스 수가 사용자가 지정한 최대값을 일시적으로 초과할 수 있습니다. 하지만 사용자가 지정한 최대 개수를 초과하는 인스턴스에 대해서는 비용이 청구되지 않습니다.

max_pending_latency

대기 지연 시간이 감소되도록 요청 처리를 위해 추가 인스턴스를 시작하기 전 App Engine이 대기 중인 대기열에서 요청 대기 시간을 허용해야 하는 최대 시간입니다. 이 임계값에 도달하면 확장이 필요하다는 신호이며, 그 결과 인스턴스 수가 증가합니다. 기본값은 '30ms'입니다.

App Engine은 `min-pending-latency` 및 `max-pending-latency`에 지정된 시간 사이에 언제라도 인스턴스를 만들 수 있습니다. 즉, App Engine은 `min-pending-latency`에 지정된 시간 전에는 대기 중인 요청을 처리하기 위해 인스턴스를 만들지 않지만, `max-pending-latency`에 도달한 후에는 인스턴스를 만듭니다.

  • 최대값이 낮으면 App Engine이 대기 중인 요청에 대해 새 인스턴스를 더 빠르게 시작하므로 성능이 향상되지만, 실행 비용도 높아집니다.
  • 최대값이 높으면 (대기 중인 요청이 있지만 이를 처리하기 위한 유휴 인스턴스가 없는 경우) 요청 처리를 위해 사용자가 더 오래 기다려야 할 수 있지만 애플리케이션 실행 비용이 낮아집니다.
min_idle_instances

실행 상태로 유지하고 트래픽 처리를 위해 준비할 인스턴스 수입니다. 트래픽 수신 여부에 관계없이 지정된 인스턴스 수에 따라 비용이 청구되니 유의하세요. 이 설정은 트래픽을 가장 많이 수신하는 버전에만 적용됩니다. 다음 사항에 유의하세요.

  • 최소값이 낮으면 유휴 기간 중 실행 비용을 낮추는 데 도움이 되지만, 부하 급증에 대응하기 위해 즉시 사용할 수 있는 인스턴스 수가 부족할 수 있습니다.
  • 최소값이 높으면 요청 부하가 급증하더라도 애플리케이션을 우선적으로 처리할 수 있습니다. App Engine은 들어오는 요청을 처리하기 위해 실행되는 최소 인스턴스 수를 유지합니다. 요청을 처리 중인지 여부에 관계없이 지정된 인스턴스 수에 따라 비용이 청구됩니다. 이 기능이 올바르게 작동하기 위해서는 준비 요청이 사용 설정되었고 애플리케이션이 준비 요청을 처리할 수 있는지 확인해야 합니다.

    유휴 인스턴스의 최소 개수를 설정하면, 대기 지연 시간이 애플리케이션 성능에 미치는 영향이 줄어듭니다. App Engine은 유휴 인스턴스를 예약된 상태로 유지하기 때문에, 갑자기 부하가 급증하는 경우를 제외하고는 요청이 대기 중인 대기열에 들어갈 가능성이 낮습니다. 예약 상태로 유지할 이상적인 인스턴스 개수를 결정하기 위해서는 애플리케이션 및 예상 트래픽 볼륨을 테스트해야 합니다.

min_pending_latency

App Engine이 요청 처리를 위해 새 인스턴스를 시작하기 전에 대기 중인 대기열에서 요청 대기 시간을 허용해야 하는 최소 시간입니다. 이 임계값에 도달하면 축소가 필요하다는 신호이며, 그 결과 인스턴스 수가 줄어듭니다. 기본값은 '30ms'입니다.

  • 최소값이 낮으면 기존의 모든 인스턴스가 활성 상태일 때 대기열에서 요청이 머물러야 하는 시간이 줄어듭니다. 따라서 성능은 향상되지만 애플리케이션 실행 비용이 높아집니다.
  • 최소값이 높으면 기존의 모든 인스턴스가 활성화 상태인 경우에 요청이 대기 중 상태로 유지되는 시간이 늘어납니다. 따라서 실행 비용은 낮아지지만 요청 처리를 위해 사용자가 기다려야 하는 시간이 늘어납니다.

service: my-service
runtime: python27
api_version: 1
instance_class: F2
automatic_scaling:
  target_cpu_utilization: 0.65
  min_instances: 5
  max_instances: 100
  min_pending_latency: 30ms  # default value
  max_pending_latency: automatic
  max_concurrent_requests: 50
basic_scaling

선택사항. basic_scaling 요소는 서비스를 위한 인스턴스 수를 설정합니다.

이 요소에는 다음 요소가 포함될 수 있습니다.

idle_timeout
선택사항. 마지막 요청을 받은 후 이 시간이 지나면 인스턴스가 종료됩니다. 기본값은 5분입니다.
max_instances
필수. App Engine이 이 서비스 버전에 대해 만들 수 있는 최대 인스턴스 수입니다. 이 요소는 서비스 비용을 제한하는 데 유용합니다.

service: my-service
runtime: python27
api_version: 1
instance_class: B8
basic_scaling:
  max_instances: 11
  idle_timeout: 10m
manual_scaling

선택사항. manual_scaling 요소는 서비스에 대해 수동 확장을 사용 설정하고 서비스를 위한 인스턴스 수를 설정합니다.

이 요소에는 다음 요소가 포함될 수 있습니다.

instances
시작 시 서비스에 할당할 인스턴스 수입니다.

service: my-service
runtime: python27
api_version: 1
instance_class: B8
manual_scaling:
  instances: 5

정적 캐시 만료

별도로 지정하지 않는 한 웹 프록시와 브라우저는 웹사이트에서 로드하는 파일을 한정된 기간 동안 유지합니다.

최상위 default_expiration 요소를 포함하면 애플리케이션의 모든 정적 파일 핸들러에 대한 전역 기본 캐시 기간을 정의할 수 있습니다. 또한 특정 정적 파일 핸들러의 캐시 기간을 구성할 수도 있습니다.

참고: 스크립트 핸들러는 적절한 HTTP 헤더를 브라우저에 반환하여 캐시 기간을 설정할 수 있습니다.

만료 시간은 Cache-ControlExpires HTTP 응답 헤더에 전송되므로, 인터넷 서비스 제공업체와 같은 중간 캐싱 프록시 서버는 물론 사용자 브라우저에서도 파일이 캐시될 수 있습니다. 만료 시간이 지정된 파일이 전송된 후에는 일반적으로 사용자가 자신의 브라우저 캐시를 지우더라도 중간 캐시에서 파일을 지울 수 있는 방법은 없습니다. 앱의 새 버전을 다시 배포해도 캐시는 재설정되지 않습니다. 따라서 정적 파일을 수정할 계획이 있다면, 만료 시간이 짧아야 합니다(1시간 미만). 대부분의 경우 만료 시간 기본값인 10분이 적합합니다.

이 페이지가 도움이 되었나요? 평가를 부탁드립니다.

다음에 대한 의견 보내기...

App Engine standard environment for Python 2