리전 ID
REGION_ID는 앱을 만들 때 선택한 리전을 기준으로 Google에서 할당하는 축약된 코드입니다. 일부 리전 ID는 일반적으로 사용되는 국가 및 주/도 코드와 비슷하게 표시될 수 있지만 코드는 국가 또는 주/도와 일치하지 않습니다. 2020년 2월 이후에 생성된 앱의 경우 REGION_ID.r이 App Engine URL에 포함됩니다. 이 날짜 이전에 만든 기존 앱의 경우 URL에서 리전 ID는 선택사항입니다.
리전 ID에 대해 자세히 알아보세요.
기존 앱을 App Engine 자바 8 런타임에서 지원되는 최신 자바 버전으로 기존 앱을 마이그레이션하려고 기존 번들 서비스를 사용하려는 경우에만 앱 구성에 appengine-web.xml 파일을 사용해야 합니다.
프로젝트에서 appengine-web.xml을 사용하는 경우 app.yaml은 배포 시 자동으로 생성됩니다.
App Engine Java 애플리케이션은 appengine-web.xml이라는 구성 파일을 사용하여 앱에 대한 정보를 지정하고 앱의 WAR 파일에서 이미지와 같은 정적 파일이 무엇인지 식별하고 애플리케이션에서 사용되는 리소스 파일을 식별합니다.
구문
App Engine Java 앱에는 appengine-web.xml 디렉터리의 WAR에 WEB-INF/이라는 파일이 있어야 합니다. 이 파일은 루트 요소가 <appengine-web-app>인 XML 파일입니다.
appengine-web.xml에 대한 문서 유형 정의와 스키마 사양은 SDK의 docs/ 디렉터리에서 찾을 수 있습니다.
| 요소 | 설명 |
|---|---|
<application> |
|
|
선택사항. 2세대 런타임용 App Engine 기존 번들 서비스를 사용하려면 이 필드를 |
|
선택사항이며 2세대 런타임에만 해당됩니다. Java 애플리케이션을 부팅하는 프로세스 명령줄인 기본 진입점을 재정의합니다. 기본적으로 F4 인스턴스 클래스에 대해 생성된 진입점(메모리 설정은 인스턴스 클래스에서 계산됨)은 다음 구성과 동일합니다. <appengine-web-app xmlns="http://appengine.google.com/ns/1.0"> <entrypoint> java -showversion -Xms32M -Xmx819M -XX:+UseG1GC -XX:+ParallelRefProcEnabled -XX:+PrintCommandLineFlags --add-opens java.base/java.lang=ALL-UNNAMED --add-opens java.base/java.nio.charset=ALL-UNNAMED --add-opens java.logging/java.util.logging=ALL-UNNAMED --add-opens java.base/java.util.concurrent=ALL-UNNAMED -Dclasspath.runtimebase=/base/java_runtime -Djava.class.path=/base/java_runtime/runtime-main.jar -Djava.library.path=/base/java_runtime: com/google/apphosting/runtime/JavaRuntimeMainWithDefaults --fixed_application_path=/workspace /base/java_runtime </entrypoint> </appengine-web-app>
JVM 프로세스 플래그를 추가하도록 구성을 수정하거나 자체 부팅 프로세스를 정의할 수 있습니다.
애플리케이션은 |
<async-session-persistence> |
선택사항. 애플리케이션이 HTTP 세션 데이터를 Datastore에 비동기식으로 쓰도록 구성하여 요청 지연 시간을 줄일 수 있습니다. <async-session-persistence enabled="true" /> 비동기 세션 지속성을 사용하면 App Engine은 데이터를 Memcache에 쓰기 전에 세션 데이터를 Datastore에 쓰는 태스크 큐 태스크를 제출합니다. 기본적으로 태스크는 `default` 큐에 제출됩니다. 다른 큐를 사용하려면 `queue-name` 속성을 추가합니다. <async-session-persistence enabled="true" queue-name="myqueue"/> 세션 데이터는 항상 동기식으로 Memcache에 기록됩니다. memcache를 사용할 수 없을 때(또는 세션 데이터가 비워졌을 때) 요청이 세션 데이터를 읽으려고 시도하면, 아직 최신 세션 데이터가 포함되지 않을 수 있는 Datastore로 장애 조치됩니다. 이는 비동기 세션 지속성으로 인해 애플리케이션에 비활성 세션 데이터가 보일 수 있음을 의미합니다. 그러나 대부분 애플리케이션의 경우, 지연 시간의 이점이 이러한 위험을 훨씬 능가합니다. |
<auto-id-policy> |
선택사항. 항목 식별자를 자동으로 설정하는 경우, 자동 ID 정책을 설정하여 사용되는 방법을 변경할 수 있습니다. 유효한 옵션은 다음과 같습니다.
|
<automatic-scaling> |
선택사항. 자세한 설명은 자동 확장 섹션을 참조하세요. |
<basic-scaling> |
선택사항. 자세한 설명은 기본 확장 섹션을 참조하세요. |
<env-variables> |
선택사항.
<env-variables> <env-var name="DEFAULT_ENCODING" value="UTF-8" /> </env-variables> 로컬 환경과의 충돌을 방지하기 위해 개발 서버는 이 파일을 바탕으로 환경 변수를 설정하지 않으며 로컬 환경에서 이러한 변수가 이미 일치하는 값으로 설정되어 있도록 요구합니다. export DEFAULT_ENCODING="UTF-8" dev_appserver war App Engine에 배포하면 이러한 변수가 이미 설정된 환경이 생성됩니다. |
<inbound-services> |
선택사항.
애플리케이션에서 이메일을 수신하려면 먼저 해당 서비스를 사용 설정하도록 애플리케이션을 구성해야 합니다.
Java 앱에 서비스를 사용 설정하려면 다음과 같은 인바운드 서비스를 사용할 수 있습니다.
|
<instance-class> |
선택사항. 이 모듈의 인스턴스 클래스 크기입니다. 다른 확장 옵션을 지정하는 경우에 다음과 같은 인스턴스 클래스를 사용할 수 있습니다.
|
<manual-scaling> |
선택사항. 자세한 설명은 수동 확장 섹션을 참조하세요. |
<precompilation-enabled> |
선택사항. App Engine은 Java 런타임 환경에서 앱의 성능을 향상시키기 위해 앱의 Java 바이트코드를 '사전 컴파일'합니다. 사전 컴파일된 코드는 원래의 바이트코드와 동일하게 작동합니다. 어떤 이유로 앱이 사전 컴파일을 사용하지 않게 하려면 <precompilation-enabled>false</precompilation-enabled> |
<module> |
참고: 서비스의 이전 명칭은 '모듈'이며 서비스를 만들 경우 필수 항목입니다. 기본 서비스의 경우에는 선택사항입니다. 각 서비스와 버전에는 이름이 있어야 합니다. 이름에는 숫자, 문자, 하이픈이 포함될 수 있습니다. 63자(영문)를 초과할 수 없으며 하이픈으로 시작하거나 끝날 수 없고 문자열 `-dot`를 포함할 수 없습니다. 각 서비스와 버전에 고유한 이름을 선택하세요. 서비스와 버전 간에 이름을 재사용하지 마세요. 서비스를 참조하세요. |
<public-root> |
선택사항.
예를 들어 다음은 URL 경로 <public-root>/static</public-root> |
<resource-files> |
선택사항.
App Engine 리소스 파일은 |
<runtime> |
지원되는 최신 자바 버전을 사용하려면 <runtime>java21</runtime> |
<service> |
서비스의 이전 명칭은 모듈입니다. 현재는 gcloud app 명령어를 통해 |
<service-account> |
선택사항. <service-account>[SERVICE_ACCOUNT_NAME]@[PROJECT_ID].iam.gserviceaccount.com</service-account> |
<sessions-enabled> |
선택사항. App Engine에는 서블릿 세션 인터페이스를 사용하여 구현된 세션이 포함됩니다. 이 구현은 지속성을 위해 Datastore의 세션 데이터를 저장하며 속도를 높이기 위해 Memcache도 사용합니다. 대부분의 다른 서블릿 컨테이너와 마찬가지로, 요청 중에 `session.setAttribute()`로 설정된 세션 속성은 요청이 끝날 때까지 지속됩니다.
이 기능은 기본적으로 사용 중지되어 있습니다. 이 기능을 사용 설정하려면 <sessions-enabled>true</sessions-enabled>
이 구현은 참고: App Engine은 Datastore와 Memcache에 세션 데이터를 저장하므로, 세션에 저장된 모든 값은 세션 데이터 스토리지 지연 시간을 줄이기 위한 방법은 |
<ssl-enabled> |
선택사항. 기본적으로 모든 사용자는 HTTP 또는 HTTPS를 사용하여 모든 URL에 액세스할 수 있습니다. 사용자는 배포 설명자의 특정 URL에 대해 HTTPS를 요구하도록 앱을 구성할 수 있습니다. 배포 설명자: 보안 URL을 참조하세요. 애플리케이션에 HTTPS 사용을 허용하지 않으려면 <ssl-enabled>false</ssl-enabled> Java 런타임 환경에서 일부 URL 경로에 대해서만 HTTPS를 허용하지 않는 방법은 없습니다. |
<static-error-handlers> |
선택사항.
특정 오류가 발생하면 App Engine은 일반 오류 페이지를 제공합니다. 커스텀 오류 데이터가 10KB 미만인 경우, 이러한 일반 오류 페이지 대신 커스텀 정적 파일을 제공하도록 앱을 구성할 수 있습니다. 앱의 <static-error-handlers> <handler file="default_error.html" /> <handler file="over_quota.html" error-code="over_quota" /> </static-error-handlers> 경고: 오류 응답 파일의 경로가 정적 파일 핸들러 경로와 겹치지 않는지 확인하세요.
각
커스텀 오류를 처리할 때 사용할 |
<static-files> |
선택사항.
<static-files>
<include path="/my_static-files" >
<http-header name="Access-Control-Allow-Origin"
value="http://example.org" />
</include>
</static-files>
|
<system-properties> |
선택사항.
<system-properties>
<property name="myapp.maximum-message-length" value="140" />
<property name="myapp.notify-every-n-signups" value="1000" />
<property name="myapp.notify-url"
value="http://www.example.com/signupnotify" />
</system-properties>
<env-variables>
<env-var name="DEFAULT_ENCODING" value="UTF-8" />
</env-variables>
자바 21부터는 가상 스레드를 사용하도록 Java 웹 서버를 구성할 수 있습니다. 예를 들면 다음과 같습니다.
<system-properties>
<property name="appengine.use.virtualthreads" value="true"/>
</system-properties>
스레드 지원에 관한 자세한 내용은 Jetty 12 – 가상 스레드 지원을 참조하세요.
|
<url-stream-handler> |
(선택사항) 가능한 값은 기본값은
<url-stream-handler>urlfetch</url-stream-handler> |
<version> |
항상 숫자로 지정되는 숫자 인스턴스와 구분되도록 버전 이름은 문자로 시작되어야 합니다. 이렇게 하면 |
<warmup-requests-enabled> |
선택사항. 기본값은 true입니다. 준비 요청은 기본적으로 Java 애플리케이션에서 사용 설정됩니다.
준비 요청이 사용 설정되면 App Engine 인프라는 준비 요청을 중지하려면 이 요소에 대해 <warmup-requests-enabled>false</warmup-requests-enabled> |
<vpc-access-connector> |
선택사항.
서버리스 VPC 액세스 커넥터를 사용하도록 애플리케이션을 구성하여 애플리케이션이 VPC 네트워크의 내부 리소스에 요청을 보낼 수 있게 합니다. <vpc-access-connector> <name>projects/[PROJECT_ID]/locations/[REGION]/connectors/[CONNECTOR_NAME]</name> </vpc-access-connector> 자세한 내용은 VPC 네트워크의 내부 리소스에 연결을 참조하세요. |
요소 확장
다음 표에는 애플리케이션 확장을 지정하는 방법을 정의하는 옵션이 나와 있습니다.
확장 유형의 성능 특징 비교에 대해서는 동적 인스턴스 확장을 참조하세요.
| 요소 | 설명 |
|---|---|
<automatic-scaling> |
선택사항. 달리 지정되지 않는 한 기본적으로 자동 확장에는 기본 인스턴스 클래스
이 요소에는 다음 요소가 포함될 수 있습니다.
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<application>simple-app</application>
<module>default</module>
<version>uno</version>
<instance-class>F2</instance-class>
<automatic-scaling>
<target-cpu-utilization>0.65</target-cpu-utilization>
<min-instances>5</min-instances>
<max-instances>100</max-instances>
<max-concurrent-requests>50</max-concurrent-requests>
</automatic-scaling>
</appengine-web-app>
|
<basic-scaling> |
선택사항.
이 요소에는 다음 요소가 포함될 수 있습니다.
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<application>simple-app</application>
<module>default</module>
<version>uno</version>
<instance-class>B8</instance-class>
<basic-scaling>
<max-instances>11</max-instances>
<idle-timeout>10m</idle-timeout>
</basic-scaling>
</appengine-web-app>
|
<manual-scaling> |
선택사항.
이 요소에는 다음 요소가 포함될 수 있습니다.
<appengine-web-app xmlns="http://appengine.google.com/ns/1.0">
<application>simple-app</application>
<module>default</module>
<version>uno</version>
<instance-class>B8</instance-class>
<manual-scaling>
<instances>5</instances>
</manual-scaling>
</appengine-web-app>
|
스테이징 요소
배포 중에 수행되는 대부분의 작업은 스테이징이라 하는 준비 단계에서 로컬로 수행되며, 이 과정에서 JAR 파일 어셈블, JSP 컴파일 등의 작업이 수행됩니다. 선택사항으로 애플리케이션 구성 파일의 스테이징 요소를 사용하여 스테이징 동작의 특정 부분을 구성할 수 있습니다. 대부분의 애플리케이션은 스테이징 동작을 수동으로 구성하지 않고도 성공적으로 배포됩니다. 앱이 배포되지 않는 경우, 아래에 있는 옵션을 사용하여 스테이징을 구성해야 할 수도 있습니다.
| 요소 | 설명 |
|---|---|
<staging> |
선택사항. 대부분의 애플리케이션은 기본 동작을 변경할 필요가 없습니다. 스테이징 요소를 사용하면 배포를 위해 필요한 경우에 특정 스테이징 구성을 지정할 수 있습니다. 이 요소에는 다음 요소가 포함될 수 있습니다.
예:
<staging>
<delete-jsps>false</delete-jsps>
</staging>
|
스테이징 옵션 기본값
스테이징 옵션의 기본값은 gcloud CLI와 같은 Google Cloud SDK 기반 도구 또는 Google Cloud SDK 기반 Maven, Gradle, Eclipse, IntelliJ 플러그인 사용 여부에 따라 다릅니다.
| 스테이징 요소 | App Engine SDK 기반 기본값 | Google Cloud SDK 기반 기본값 |
|---|---|---|
enable-jar-splitting |
false |
true |
jar-splitting-excludes |
해당 없음 | 해당 없음 |
disable-jar-jsps |
false |
false |
enable-jar-classes |
false |
true. 클래스 로딩 순서에 영향을 줄 수 있으므로, 앱이 이전의 false 기본값을 사용하여 특정 순서에 의존하는 경우에는 이 요소를 false로 설정할 수 있습니다. |
delete-jsps |
false |
true |
compile-encoding |
utf-8 |
utf-8 |
포함 및 제외 구문
경로 패턴은 <include> 및 <exclude> 요소를 0개 이상의 사용하여 지정됩니다. 패턴에서 '*'는 파일 또는 디렉터리 이름의 문자를 0개 이상 나타내고, **는 경로에 있는 디렉터리를 0개 이상 나타냅니다. 앱을 App Engine에 배포하면 <exclude> 패턴과 일치하는 파일과 디렉터리는 업로드되지 않습니다. 단, 로컬 개발 서버에서 실행하는 경우에는 이러한 파일과 디렉터리는 애플리케이션에 계속 액세스할 수 있습니다.
<include> 요소는 모든 파일을 포함하는 기본 동작을 재정의합니다. <exclude> 요소는 모든 <include> 패턴(그리고 <include>를 명시적으로 제공하지 않은 경우에는 기본값) 이후에 적용됩니다.
다음 예시는 모든 .png 파일(data/ 디렉터리와 해당 하위 디렉터리의 파일 제외)을 정적 파일로 지정하는 방법을 보여줍니다.
<static-files>
<include path="/**.png" />
<exclude path="/data/**.png" />
</static-files>
이러한 정적 리소스에 대한 요청 응답 시에 사용할 HTTP 헤더를 설정할 수도 있습니다.
<static-files>
<include path="/my_static-files" >
<http-header name="Access-Control-Allow-Origin"
value="http://example.org" />
</include>
</static-files>
정적 파일의 MIME 유형
기본적으로 정적 파일은 파일 이름 확장명에 따라 선택된 MIME 유형을 사용하여 제공됩니다. web.xml에서 mime-mapping 요소를 사용하여 정적 파일의 파일 이름 확장명에 커스텀 MIME 유형을 연결할 수 있습니다.
URLFetch 제한 시간
각 URLFetch 요청에 기한을 설정할 수 있습니다. 기본적으로 가져오기 기한은 5초입니다.
appengine-web.xml 구성 파일에 다음 설정을 포함하여 이 기본값을 변경할 수 있습니다. 다음 명령어를 입력하여 시간 제한을 초 단위로 지정합니다.
<system-properties>
<property name="appengine.api.urlfetch.defaultDeadline" value="10"/>
</system-properties>