Go 1.11은 지원이 종료되었으며 2026년 1월 31일에 지원 중단됩니다. 지원 중단 후에는 조직에서 이전에 조직 정책을 사용하여 레거시 런타임의 배포를 다시 사용 설정한 경우에도 Go 1.11 애플리케이션을 배포할 수 없습니다. 기존 Go 1.11 애플리케이션은 지원 중단 날짜 이후에도 계속 실행되고 트래픽을 수신합니다. 지원되는 최신 Go 버전으로 마이그레이션하는 것이 좋습니다.
이 페이지에서는 내보내기 작업을 처리하는 코드인 작업 핸들러를 만드는 방법을 설명합니다. 태스크를 처리하려면 요청 핸들러를 제공해야 합니다. 요청 URL과 해당 핸들러 간의 매핑은 다른 요청 핸들러와 마찬가지로 서비스의 app.yaml에서 선언합니다. 태스크 요청을 핸들러에 매핑하는 방법을 사용자가 직접 제어하므로 태스크 핸들러를 원하는 대로 구성할 수 있습니다. 애플리케이션이 여러 종류의 태스크를 처리하는 경우 모든 핸들러를 단일 서비스에 추가하거나 여러 서비스에 분산할 수 있습니다.
push 태스크 요청 핸들러 작성
큐에서 태스크 큐 서비스는 HTTP 헤더를 만들어 태스크 대상에서 지정된 작업자 서비스 인스턴스로 전송합니다. 태스크 큐 요청은 IP 주소 0.1.0.2에서 전송됩니다.
핸들러가 별도의 서비스에 있는 경우 태스크를 만들고 큐에 추가할 때 사용한 것과 동일한 언어로 핸들러를 작성할 필요가 없습니다.
핸들러를 작성할 때 다음 가이드라인을 준수하세요.
코드는 200~299 범위 내의 HTTP 상태 코드를 반환하여 태스크가 성공했음을 표시해야 합니다. 다른 코드는 태스크가 실패했음을 나타냅니다.
Push 태스크에는 고정된 완료 기한이 있으며, 이는 해당 태스크를 실행하는 서비스의 확장 유형에 따라 달라집니다.
자동 확장 서비스는 10분 이내에 완료되어야 합니다.
수동 및 기본 확장 서비스는 최대 24시간 실행될 수 있습니다. 핸들러가 기한을 넘기면 태스크 큐 서비스는 태스크를 실패로 간주하고 다시 시도합니다.
핸들러는 멱등성이 있어야 합니다.
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일부터의 경과 시간(초)으로 지정됩니다.
요청 핸들러가 위에 나열된 헤더를 찾은 경우, 해당 요청이 태스크 큐 요청임을 신뢰할 수 있습니다.
데이터 수정과 같은 민감한 작업을 수행하는 경우, 악의적인 외부 사용자가 직접 호출할 수 없도록 핸들러 URL을 보호할 수 있습니다. App Engine 관리자에게만 액세스를 부여하여 사용자가 태스크 URL에 액세스하지 못하도록 할 수 있습니다. 태스크 요청 자체는 App Engine에서 발생되므로, 항상 제한된 URL을 타겟팅할 수 있습니다.
app.yaml 파일의 핸들러 구성에 login: admin 요소를 추가하여 URL을 제한할 수 있습니다.
[[["이해하기 쉬움","easyToUnderstand","thumb-up"],["문제가 해결됨","solvedMyProblem","thumb-up"],["기타","otherUp","thumb-up"]],[["이해하기 어려움","hardToUnderstand","thumb-down"],["잘못된 정보 또는 샘플 코드","incorrectInformationOrSampleCode","thumb-down"],["필요한 정보/샘플이 없음","missingTheInformationSamplesINeed","thumb-down"],["번역 문제","translationIssue","thumb-down"],["기타","otherDown","thumb-down"]],["최종 업데이트: 2025-09-04(UTC)"],[[["\u003cp\u003eTask handlers are request handlers that process push tasks, with the mapping from request URLs to handlers defined in the service's \u003ccode\u003eapp.yaml\u003c/code\u003e file.\u003c/p\u003e\n"],["\u003cp\u003eTask handlers must return an HTTP status code between 200-299 to indicate success, with any other code signifying failure and triggering a retry, and the code must be idempotent.\u003c/p\u003e\n"],["\u003cp\u003eApp Engine sets specific HTTP headers in Task Queue requests, such as \u003ccode\u003eX-Appengine-QueueName\u003c/code\u003e, \u003ccode\u003eX-Appengine-TaskName\u003c/code\u003e, and \u003ccode\u003eX-Appengine-TaskRetryCount\u003c/code\u003e, to provide task-specific information.\u003c/p\u003e\n"],["\u003cp\u003eTo secure sensitive task handler URLs, you can restrict access to App Engine administrators by using the \u003ccode\u003elogin: admin\u003c/code\u003e element in the \u003ccode\u003eapp.yaml\u003c/code\u003e file's handler configuration.\u003c/p\u003e\n"],["\u003cp\u003eTask Queue requests are sent from the IP address 0.1.0.2, and the code for the task handler does not have to be written in the same language as the code that enqueued the task.\u003c/p\u003e\n"]]],[],null,["# Creating Task Handlers\n\nThis page describes how to create a *task handler* , the code that handles a push\ntask. You must provide a request handler to process the task. The mapping from\nthe request URL to the appropriate handler is declared in your service's `app.yaml`, just\nlike any other request handler. Because you control how to map task requests to\na handler, you're free to organize your task handlers. If your application\nprocesses many different kinds of tasks, you can add all the handlers to a\nsingle service, or you can distribute them among multiple services.\n| This API is supported for first-generation runtimes and can be used when [upgrading to corresponding second-generation runtimes](/appengine/docs/standard/\n| go\n| /services/access). If you are updating to the App Engine Go 1.12+ runtime, refer to the [migration guide](/appengine/migration-center/standard/migrate-to-second-gen/go-differences) to learn about your migration options for legacy bundled services.\n\nWriting a push task request handler\n-----------------------------------\n\nIn the queue, the Task Queue service creates an HTTP header and sends it to an\ninstance of the worker service specified by the task's target. Task Queue requests are\nsent from the IP address `0.1.0.2`.\n\nYour handler does not need to be written in the same language that created and\nenqueued the task if the handler is in a\n[separate service](/appengine/docs/legacy/standard/go111/an-overview-of-app-engine).\n\nWhen you write your handler, follow these guidelines:\n\n- The code must return an HTTP status code within the range 200--299 to\n indicate success. Any other code indicates that the task failed.\n\n | **Note:** App Engine itself returns a `503` status code when instances are overloaded or otherwise unavailable. The Task Queue service responds to this by slowing delivery from queues to handlers, to avoid making the problem worse. If you wish to trigger a retry intentionally, use any status code *other* than `2xx` or `503`.\n- Push tasks have a fixed [completion\n deadline](/appengine/docs/legacy/standard/go111/taskqueue/push#the_task_deadline)\n that depends on the scaling type of the service that's running them.\n Automatic scaling services must finish before 10 minutes have elapsed.\n Manual and basic scaling services can run up to 24 hours. If your handler\n misses the deadline, the Task Queue service assumes the task failed and\n will retry it.\n\n \u003cbr /\u003e\n\n- The handler must be [idempotent](https://wikipedia.org/wiki/idempotent).\n App Engine's Task Queue API is designed to provide \"at least once\"\n delivery; that is, if a task is successfully added, App Engine will deliver\n it to a handler at least once. Note that in some rare circumstances, multiple task\n execution is possible, so your code must ensure that there are no harmful\n side-effects of repeated execution.\n\nTask Queue uses the HTTP code in the handler's response to determine if the\ntask succeeded. The response from the handler is seen only by the Task Queue service\nand only to determine if the task succeeded. The queue ignores all other fields\nin the response. Then the service discards the response. The originating app **never\nreceives** any of the data. If a task fails, the Task Queue service retries the\ntask by sending another request.\n\nUser-supplied data can be delivered to the handler in the request as a query string or as a\npayload in the request body. Inserting user data is described in\n[Creating Tasks](/appengine/docs/legacy/standard/go111/taskqueue/push/creating-tasks#adding_user_data). If the request includes data, the handler must know how\nit was inserted into the request. The exact code you use to fetch the data from\nthe request depends on the particular web framework you're using.\n\nTo test a task handler, sign in as an administrator and visit the handler's URL in your browser.\n\nReading request headers\n-----------------------\n\nA push task HTTP request has special headers set by App Engine, which contain\ntask-specific information your handler can use.\n\nIf these headers are present in an external user request to your app, they are stripped\nand replaced. The sole exception is for requests from logged-in administrators\nof the application, who are allowed to set headers for testing purposes. On the other hand, headers\nare not removed when your app is running in the development server.\n\nRequests from Task Queue will always contain the following headers:\n\nIf your request handler finds any of the headers listed above, it can trust that\nthe request is a Task Queue request.\n\nIn addition, requests from Task Queue can contain the following headers:\n\nSecuring task handler URLs\n--------------------------\n\nIf a task performs sensitive operations (such as modifying data), you might want to secure the handler URL to prevent a malicious external user from calling it directly. You can prevent users from accessing task URLs by restricting access to\n[App Engine administrators](/appengine/docs/legacy/standard/go111/access-control). Task requests themselves are\nissued by App Engine and can always target a restricted URL.\n\nYou can restrict a URL by adding the\n[`login: admin`](/appengine/docs/legacy/standard/go111/config/appref#handlers-login)\nelement to the handler configuration in your `app.yaml` file.\n\nFor example: \n\n runtime: go\n api_version: go1\n\n handlers:\n - url: /worker/.*\n script: _go_app\n login: admin\n - url: /.*\n script: _go_app\n\n| **Note:** While tasks can use URL paths restricted with `login: admin`, they *cannot* use URL paths restricted with `login: required` because tasks are not run as any user. The `admin` restriction is satisfied by the inclusion of the `X-Appengine-QueueName` header described in [Reading request headers](#reading_request_headers).\n\nWhat's next\n-----------\n\n- Learn how to [delete tasks](/appengine/docs/legacy/standard/go111/taskqueue/push/deleting-tasks-and-queues)"]]
