queue.yaml 참조

리전 ID

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

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

queue.yaml 구성 파일은 앱에서 사용하는 거의 모든 태스크 큐(push 또는 pull)를 만들고 구성하는 데 사용됩니다. 모든 App Engine 앱에는 default라는 자동으로 사전 구성된 push 큐가 함께 제공됩니다. default 큐를 직접 만들지 않지만 다른 큐를 추가하거나 queue.yaml 파일을 사용하여 default 큐 구성을 변경할 수 있습니다.

자바 앱의 경우 이 파일은 소스 코드 디렉터리에서 임의의 위치에 저장됩니다.

push 큐를 구성하려면 Cloud Tasks에서 queue.yaml 또는 큐 관리 메서드를 사용할 수 있지만 동시 둘 다 사용할 수는 없습니다. queue.yaml 업로드 메서드와 큐 관리 메서드를 함께 사용하면 예기치 않은 결과가 발생할 수 있으므로 권장되지 않습니다.

pull 큐를 구성하려면 queue.yaml 파일을 사용해야 합니다.

예

다음은 이름이 지정된 큐를 정의하고 기본 처리 속도를 재정의하는 기본 예입니다.

queue:
- name: my-push-queue
  rate: 1/s

다음은 태스크 시도 횟수를 설정하고 기본 처리 속도를 수정하는 방법을 보여주는 보다 복잡한 queue.yaml 구성의 예시입니다.

queue:
- name: fooqueue
  rate: 1/s
  retry_parameters:
    task_retry_limit: 7
    task_age_limit: 2d
- name: barqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 0
- name: bazqueue
  rate: 1/s
  retry_parameters:
    min_backoff_seconds: 10
    max_backoff_seconds: 200
    max_doublings: 3

구문

queue.yaml 파일은 루트 지시문이 queue인 YAML 파일입니다. 이 지시문에는 이름이 지정된 큐가 0개 이상 포함됩니다. 각 큐 정의에 지정할 수 있는 요소는 다음과 같습니다.

요소 설명
<bucket-size>(push 큐)

선택사항. 태스크 큐는 토큰 버킷 알고리즘을 사용하여 태스크 실행 속도를 제어합니다. 이름이 지정된 각 큐에는 bucket_size 값으로 지정된 최댓값까지 토큰이 저장된 토큰 버킷이 포함됩니다. 애플리케이션이 태스크를 실행할 때마다 토큰이 버킷에서 삭제됩니다. 큐의 버킷에 토큰이 없어질 때까지 큐의 태스크 처리가 계속됩니다. App Engine은 큐에 지정된 속도에 따라 버킷에 새 토큰을 계속 다시 채웁니다.

버킷 크기는 큐에 많은 태스크가 있고 속도가 빠른 경우에 큐가 처리되는 속도를 제한합니다. 버킷 크기 최댓값은 500입니다. 이를 통해 태스크가 큐에 추가된 직후부터 처리가 시작되도록 빠른 속도를 유지하면서도 짧은 기간 동안 많은 태스크가 큐에 추가되면 리소스 사용량을 제한할 수 있습니다.

큐의 bucket_size를 지정하지 않으면 기본값은 5입니다. 기본 크기는 많은 사용 사례에서 너무 작을 수 있으므로 이 값을 더 크게 설정하는 것이 좋습니다. 예를 들어 처리 속도를 기준으로 버킷 크기를 결정할 수 있습니다.

이 요소에 대한 자세한 내용은 Cloud Tasks API 참조의 max_burst_size

비교 설명을 참조하세요.
<max-concurrent-requests>(push 큐)

선택사항. 지정된 큐에서 동시에 실행할 수 있는 최대 태스크 수를 설정합니다. 이 값은 정수입니다. 기본적으로 태스크는 큐당 1,000개로 제한됩니다. 권장 최대 한계는 큐당 태스크 5,000개입니다. 큐가 처음 생성되었거나 한동안 유휴 상태였으면 큐의 처리량이 천천히 늘어날 수 있습니다.

동시 태스크 수를 제한하면 큐의 실행 속도를 더 세밀하게 제어하면서 한 번에 너무 많은 태스크가 실행되는 것을 방지할 수 있습니다. 또한 Datastore 경합을 방지하고 다른 큐 또는 온라인 처리를 위한 리소스를 확보할 수 있습니다.

이 요소에 대한 자세한 내용은 Cloud Tasks API 참조의 max_concurrent_dispatches 비교 설명을 참조하세요.
<mode>

선택사항. 큐 모드를 식별합니다. 이 설정의 기본값은 push이며 큐를 push 큐로 식별합니다. pull 큐를 사용하려면 모드를 pull로 설정합니다.

<name>

필수. 큐의 이름입니다. QueueFactory.getQueue()를 호출할 때 지정하는 이름입니다.

큐 이름에는 대문자와 소문자, 숫자, 하이픈이 포함될 수 있습니다. 큐 이름 최대 길이는 100자입니다.

모든 앱에는 이름이 default인 push 큐가 있습니다. 이 큐의 속도는 초당 태스크 5개로 미리 설정되어 있습니다. 이 기본 큐는 처음 사용되거나 구성될 때까지 Google Cloud 콘솔에 표시되지 않습니다. queue.yaml 파일에 `default`라는 큐를 정의하여 기본 비율 변경을 포함한 기본 큐를 구성할 수 있습니다.

<rate>(push 큐)

필수. 이 큐에서 태스크가 처리되는 빈도입니다. 값은 숫자, 슬래시, 시간 단위로 표시됩니다. 단위는 s(초), m(분), h(시간) 또는 d(일)입니다. 예를 들어 5/m 값은 태스크가 분당 5회 속도로 처리된다는 의미입니다. rate의 최댓값은 500/s입니다.

숫자가 0(예: 0/s)이면 큐가 '일시중지'된 것으로 간주되어 어떠한 태스크도 처리되지 않습니다.

이 요소에 대한 자세한 내용은 Cloud Tasks API 참조의 max_dispatches_per_second 비교 설명을 참조하세요.
<retry-parameters>

선택사항. Push 큐에서 실패한 태스크의 재시도 횟수를 구성합니다. 이렇게 하면 특정 큐에서 실패한 태스크를 다시 시도할 최대 횟수를 지정할 수 있습니다. 또한 재시도 제한 시간을 설정하고 재시도 사이의 간격을 제어할 수 있습니다.

retry 매개변수에는 다음과 같은 하위 요소가 포함될 수 있습니다.

<task-retry-limit>
재시도 횟수입니다. 예를 들어 0을 지정하면 태스크가 실패해도 재시도되지 않습니다. 1을 지정한 경우 태스크가 실패하면 태스크가 한 번만 재시도됩니다. 이 매개변수를 지정하지 않으면 태스크가 무한정 재시도됩니다. task_retry_limit가 task_age_limit와 함께 지정되면 두 값 모두 한도에 도달할 때까지 태스크가 재시도됩니다.
<task-age-limit>(push 큐)
실패한 태스크를 다시 시도하기 위한 시간 제한으로, 태스크가 처음 실행된 시점을 기준으로 측정됩니다. 숫자 뒤에 시간 단위를 붙인 값으로, 단위는 s(초), m(분), h(시간), d(일)입니다. 예를 들어 5d 값은 태스크의 첫 실행 시도 후 5일을 제한 시간으로 지정합니다. 이 매개변수를 지정하지 않으면 태스크가 무한정 재시도됩니다. task_retry_limit로 지정하면 App Engine은 두 값 모두 한도에 도달할 때까지 태스크를 다시 시도합니다.
<min-backoff-seconds>(push 큐)
태스크 실패 후 태스크를 다시 시도하기 전에 기다릴 최소 시간(초)입니다. 기본값은 0.1입니다.
<max-backoff-seconds>(push 큐)
태스크 실패 후 태스크를 다시 시도하기 전에 기다릴 최대 시간(초)입니다. 기본값은 3600입니다.
<max-doublings>(push 큐)
실패한 태스크 다시 시도 사이의 간격이 두 배가 되는 최대 횟수입니다. 이 횟수 이후에는 증분 값이 상수가 됩니다. 이 상수는 2**max_doublings * min_backoff_seconds입니다. 기본값은 16입니다.
<target>(push 큐)

선택사항. 이 큐에 추가되는 모든 태스크를 실행할 서비스/버전, 프런트엔드 버전 또는 백엔드 이름을 지정하는 문자열입니다. 기본값은 빈 문자열입니다.

이 문자열은 태스크를 위한 HTTP 요청 생성 시 앱의 도메인 이름 앞에 추가됩니다. 예를 들어 앱 ID가 my-app이고 대상을 my-version-dot-my-service로 설정하면 URL 호스트 이름은 my-version-dot-my-service-dot-my-app.REGION_ID.r.appspot.com으로 설정됩니다.

타겟을 지정하지 않으면 큐에 추가된 것과 동일한 버전의 애플리케이션에서 태스크가 호출됩니다. 따라서 큐에서 타겟을 지정하지 않고 기본 애플리케이션 버전에서 태스크를 큐에 추가하면 기본 애플리케이션 버전에서 태스크가 호출됩니다. 태스크가 큐에 추가된 시점과 태스크가 실행되는 시점 사이에서 기본 애플리케이션 버전이 변경되면 태스크는 새로운 기본 버전에서 실행됩니다.

디스패치 파일과 함께 서비스를 사용하는 경우, 작업의 HTTP 요청은 가로채기되어 다른 서비스로 다시 라우팅될 수 있습니다.

앱에 포함된 모든 큐에 지정할 수 있는 요소는 다음과 같습니다.

요소 설명
<total-storage-limit>

선택사항. 태스크 큐 스토리지에 사용할 수 있는 기본 할당량 스토리지 한도(100M)를 재정의하는 문자열입니다. 예를 들면 다음과 같습니다. 

<queue-entries>
  <total-storage-limit>1.2G</total-storage-limit>
  <queue>
    <name>fooqueue</name>
  </queue>
</queue-entries>

이 할당량은 애플리케이션의 총 스토리지 할당량(Datastore 및 Blobstore 할당량 포함)에 합산됩니다.

서픽스를 지정하지 않으면 지정된 숫자가 바이트로 해석됩니다. 지원되는 서픽스는 다음과 같습니다.

  • B(바이트)
  • K(킬로바이트)
  • M(메가바이트)
  • G(기가바이트)
  • T(테라바이트)

<total-storage-limit>가 애플리케이션에서 사용할 수 있는 총 디스크 저장용량을 초과하면 한도는 사용 가능한 스토리지로 제한됩니다.

큐 구성 파일 배포

queue.yaml 파일은 소스 코드 디렉터리의 어디에나 상주할 수 있습니다.

현재 제공 중인 버전을 변경하지 않고 큐 구성 파일을 배포하려면 큐 파일이 포함된 디렉터리에서 환경에 따라 다음 명령 중 하나를 사용합니다.

gcloud

gcloud app deploy queue.yaml

Maven

mvn appengine:deployQueue queue.yaml

Gradle

gradle appengineDeployQueue queue.yaml

IDE

IntelliJ 또는 Eclipse를 사용하는 경우 배포 양식을 사용하여 배포할 개별 구성 파일을 선택합니다.

큐 삭제

큐를 삭제하려면 다음 안내를 따르세요.

  1. queue.yaml 파일에서 큐 정의를 삭제합니다.

  2. queue.yaml 파일의 변경사항을 업로드합니다.

    gcloud app deploy queue.yaml

  3. Google Cloud 콘솔에서 큐를 삭제하려면 큐를 선택한 후 큐 삭제를 클릭합니다.

    태스크 큐 페이지로 이동

Google Cloud 콘솔에서 큐를 삭제한 경우 동일한 이름의 큐를 다시 만들려면 7일을 기다려야 합니다.