태스크 핸들러 만들기

이 페이지에서는 내보내기 작업을 처리하는 코드인 작업 핸들러를 만드는 방법을 설명합니다. 태스크를 처리하려면 요청 핸들러를 제공해야 합니다. 요청 URL과 해당 핸들러 간의 매핑은 다른 요청 핸들러와 마찬가지로 서비스의 web.xml에서 선언합니다. 태스크 요청을 핸들러에 매핑하는 방법을 사용자가 직접 제어하므로 태스크 핸들러를 원하는 대로 구성할 수 있습니다. 애플리케이션이 여러 종류의 태스크를 처리하는 경우 모든 핸들러를 단일 서비스에 추가하거나 여러 서비스에 분산할 수 있습니다.

push 태스크 요청 핸들러 작성

큐에서 태스크 큐 서비스는 HTTP 헤더를 만들어 태스크 대상에서 지정된 작업자 서비스 인스턴스로 전송합니다. 태스크 큐 요청은 IP 주소 0.1.0.2에서 전송됩니다.

핸들러가 별도의 서비스에 있는 경우 태스크를 만들고 큐에 추가할 때 사용한 것과 동일한 언어로 핸들러를 작성할 필요가 없습니다.

핸들러를 작성할 때 다음 가이드라인을 준수하세요.

  • 코드는 200~299 범위 내의 HTTP 상태 코드를 반환하여 태스크가 성공했음을 표시해야 합니다. 다른 코드는 태스크가 실패했음을 나타냅니다.

  • Push 태스크에는 고정된 완료 기한이 있으며, 이는 해당 태스크를 실행하는 서비스의 확장 유형에 따라 달라집니다. 자동 확장 서비스는 10분 이내에 완료되어야 합니다. 수동 및 기본 확장 서비스는 최대 24시간 실행될 수 있습니다. 핸들러가 기한을 넘기면 태스크 큐 서비스는 태스크를 실패로 간주하고 다시 시도합니다.

    태스크 실행 시간이 기한에 가까워지면 기한에 도달하기 전에 App Engine이 DeadlineExceededException을 발생시키므로 작업을 저장하거나 진행 상황을 로깅할 수 있습니다.

  • 핸들러는 멱등성이 있어야 합니다. App Engine의 Task Queue API는 '최소 1회' 전송할 수 있도록 설계되었습니다. 즉, 태스크가 성공적으로 추가되면 App Engine은 이 태스크를 최소 1회 이상 핸들러에 전달합니다. 드물지만 여러 태스크를 실행할 수 있는 경우가 있으므로, 반복 실행으로 인해 유해한 부작용이 발생하지 않도록 코드를 작성해야 합니다.

태스크 큐는 핸들러의 응답에서 HTTP 코드를 사용하여 태스크의 성공 여부를 확인합니다. 핸들러의 응답은 태스크 큐 서비스를 통해서만 확인할 수 있으며 태스크 성공 여부만 확인할 수 있습니다. 큐는 응답의 다른 필드를 모두 무시합니다. 그런 다음 서비스는 응답을 삭제합니다. 응답을 보낸 앱에는 어떠한 데이터도 수신되지 않습니다. 태스크가 실패하면 태스크 큐 서비스가 다른 요청을 보내 태스크를 다시 시도합니다.

사용자가 제공한 데이터는 요청에서 쿼리 문자열 또는 요청 본문의 페이로드로 핸들러에 전달될 수 있습니다. 사용자 데이터 삽입에 대해서는 태스크 만들기에서 설명합니다. 요청에 데이터가 포함된 경우 핸들러는 데이터가 요청에 삽입된 방법을 알아야 합니다. 요청에서 데이터를 가져오는 데 사용되는 정확한 코드는 사용 중인 특정 웹 프레임워크에 따라 달라집니다.

태스크 핸들러를 테스트하려면 관리자로 로그인하고 브라우저에서 핸들러 URL로 이동합니다.

요청 헤더 읽기

Push 태스크 HTTP 요청에는 App Engine에서 설정된 특수 헤더가 있습니다. 이 특수 헤더에는 핸들러가 사용할 수 있는 태스크별 정보가 포함되어 있습니다.

이러한 헤더가 앱에 대한 외부 사용자 요청에 있는 경우, 해당 헤더는 제거되고 대체됩니다. 테스트용 헤더를 설정할 수 있는 로그인한 애플리케이션 관리자가 보내는 요청만이 유일한 예외입니다. 반면 앱이 개발 서버에서 실행 중인 경우에는 헤더가 삭제되지 않습니다.

태스크 큐의 요청에는 항상 다음 헤더가 포함됩니다.

헤더 설명
X-Appengine-QueueName 큐 이름입니다(기본 push 큐의 경우 'default'일 수 있음).
X-Appengine-TaskName 태스크 이름 또는 이름이 지정되지 않은 경우에는 시스템에서 생성된 고유 ID입니다.
X-Appengine-TaskRetryCount 이 태스크가 다시 시도된 횟수입니다. 첫 시도의 경우, 이 값은 0입니다. 사용 가능한 인스턴스가 부족하여 태스크가 실패하고 실행 단계에 도달하지 못한 시도도 이 숫자에 포함됩니다.
X-Appengine-TaskExecutionCount 이 태스크가 이전의 실행 단계 중에 실패한 횟수입니다. 사용할 수 있는 인스턴스가 부족하여 실패한 경우는 이 숫자에 포함되지 않습니다.
X-Appengine-TaskETA 태스크의 목표 실행 시간으로, 1970년 1월 1일부터의 경과 시간(초)으로 지정됩니다.

요청 핸들러가 위에 나열된 헤더를 찾은 경우, 해당 요청이 태스크 큐 요청임을 신뢰할 수 있습니다.

또한 태스크 큐의 요청에는 다음 헤더가 포함될 수 있습니다.

헤더 설명
X-Appengine-TaskPreviousResponse 지난번 재시도에서 나온 HTTP 응답 코드입니다.
X-Appengine-TaskRetryReason 태스크를 다시 시도하는 이유입니다.
X-Appengine-FailFast 기존 인스턴스를 사용할 수 없으면 실행 중인 태스크가 즉시 실패함을 나타냅니다.

태스크 핸들러 URL 보호

데이터 수정과 같은 민감한 태스크를 수행하는 경우, 악의적인 외부 사용자가 직접 호출할 수 없도록 핸들러 URL을 보호할 수 있습니다. App Engine 관리자에게만 액세스를 부여하여 사용자가 태스크 URL에 액세스하지 못하도록 할 수 있습니다. 태스크 요청 자체는 App Engine에서 발생되므로, 항상 제한된 URL을 타겟팅할 수 있습니다.

보안 및 인증에서 URL 제한에 대해 알아볼 수 있습니다. 다음은 web.xml에서 /tasks/로 시작하는 모든 항목을 관리자 전용으로 제한하는 예시입니다.

<security-constraint>
    <web-resource-collection>
        <web-resource-name>tasks</web-resource-name>
        <url-pattern>/tasks/*</url-pattern>
    </web-resource-collection>
    <auth-constraint>
        <role-name>admin</role-name>
    </auth-constraint>
</security-constraint>

web.xml 형식에 대한 자세한 내용은 배포 설명자에 대한 문서를 참조하세요.

다음 단계