HTTP Targets가 출시됨에 따라 이제 공개 IP 주소를 갖는 모든 HTTP 엔드포인트(예: Cloud Functions, Cloud Run, GKE, Compute Engine, 심지어 온프렘 웹 서버도)에서 Cloud Tasks 핸들러를 실행할 수 있습니다. 안정적이고 구성 가능한 방식으로 이러한 서비스에서 작업을 실행할 수 있습니다.
이 페이지에서는 프로그래매틱 방식으로 HTTP Target 작업을 만들어 Cloud Tasks 큐에 배치하는 방법을 보여줍니다. 작업을 처리하려면 새 작업 객체를 만들어 큐에 추가해야 합니다. 작업을 처리하는 서비스와 핸들러를 지정하고 필요에 따라 작업별 데이터를 핸들러에 함께 전달할 수 있습니다. 작업 실행 시간을 예약하거나 작업이 실패할 경우 재시도할 횟수를 제한하는 등 작업의 구성을 세부적으로 조정할 수도 있습니다. 작업의 이름을 지정하면 Cloud Tasks에서 이 이름을 사용하여 작업 중복 삭제를 진행할 수 있지만, 이에 필요한 처리로 지연 시간이 늘어날 수 있습니다.
일반적으로 HTTP 요청 형식으로 작업을 만듭니다. 아래의 샘플과 같이 Google Cloud 클라이언트 라이브러리와 서비스 계정을 사용하면 Cloud Tasks 서버와의 통신 세부정보를 관리하여 작업을 더 쉽게 생성할 수 있습니다.
HTTP Target 작업 만들기
다음 예시에서는 작업을 생성하는 HTTP Target 작업 요청을 만듭니다. 작업 핸들러의 URL이 포함됩니다.
C#
Python
requirements.txt
파일을 확인합니다.
자바
pom.xml
파일을 확인합니다.
PHP
composer.json
파일을 확인합니다.
Go
Node.js
package.json
파일을 확인합니다.
Ruby
HTTP Target 핸들러 인증을 위한 서비스 계정 설정
Cloud Tasks는 핸들러에 접근할 적절한 사용자 인증 정보가 있는 서비스 계정을 가진 경우 인증이 필요한 HTTP Target 핸들러를 호출할 수 있습니다.
사용하려는 현재 서비스 계정이 있는 경우 가능합니다. 적절한 역할을 부여하기만 하면 됩니다. 이 안내에서는 이 기능에 필요한 새 서비스 계정 생성에 대해 다룹니다.
서비스 계정 콘솔 페이지로 이동합니다.
필요한 경우 적절한 프로젝트를 선택합니다.
+ 서비스 계정 만들기를 클릭합니다.
계정에 표시 이름을 지정하세요. 콘솔이 계정의 관련 이메일 계정 이름을 생성합니다. 이런 방식으로 계정을 참조합니다. 원하는 경우 계정에 대한 설명을 추가할 수도 있습니다.
만들기를 클릭합니다. 서비스 계정 권한 화면으로 이동합니다.
역할 선택 드롭다운을 클릭합니다.
왼쪽 열에서 Cloud Tasks로 스크롤하고 오른쪽에서 Cloud Tasks 큐 추가자를 선택합니다. 이렇게 하면 작업을 큐에 추가 할 수 있는 권한이 서비스 계정에 부여됩니다.
+ 다른 역할 추가를 클릭합니다.
새 역할 선택 드롭다운을 클릭합니다.
왼쪽 열에서 서비스 계정으로 스크롤하고 오른쪽에서 서비스 계정 사용자를 선택합니다. 이 역할을 사용하면 서비스 계정의 사용자 인증 정보를 사용하여 대신 토큰을 만들도록 서비스 계정에서 큐를 승인할 수 있습니다.
핸들러가 Google Cloud의 일부인 경우 핸들러가 실행 중인 서비스에 액세스하는 것과 관련된 역할을 서비스 계정에 부여하세요. Google Cloud에 포함된 각 서비스에는 서로 다른 역할이 필요합니다. 예를 들어 Cloud Run에서 핸들러에 액세스하려면 Cloud Run 호출자 역할이 필요한 것 등입니다. 방금 만든 서비스 계정 또는 프로젝트의 다른 서비스 계정을 사용할 수 있습니다.
Cloud Tasks 자체에는
Cloud Tasks Service Agent
역할이 부여된 자체 서비스 계정이 있어야 합니다. 이렇게 하면 Cloud Tasks 서비스 계정과 연결된 사용자 인증 정보를 기반으로 헤더 토큰을 생성하여 핸들러 대상으로 인증할 수 있습니다. Cloud Tasks API를 사용 설정하면 이 역할이 부여된 Cloud Tasks 서비스 계정이 자동으로 생성됩니다. 단, API를 2019년 3월 19일 이전에 사용 설정했다면 역할을 수동으로 추가해야 합니다.
인증 토큰이 포함된 HTTP Target 작업 사용
Cloud Tasks와 HTTP Target 핸들러 간의 인증을 위해 Cloud Tasks는 헤더 토큰을 만듭니다. 이 토큰은 이메일 주소로 식별되는 Cloud Tasks Enqueuer
서비스 계정의 사용자 인증 정보를 기반으로 합니다.
토큰과 함께 요청이 HTTPS를 통해 큐에서 핸들러로 전송됩니다.
이때 OIDC 토큰 또는 OAuth 토큰을 사용할 수 있습니다. OIDC 토큰은 서명된 JSON 웹 토큰(JWT)이며 주로 ID를 어설션하고, 액세스를 제공하는 OAuth 토큰과는 달리 암시적 승인을 제공하지 않습니다. OIDC 토큰은 일반적으로 Cloud Functions 또는 Cloud Run과 같은 Google Cloud에서 실행되는 모든 핸들러에 사용해야 합니다.
예외는 OAuth 토큰을 필요로 하는 *.googleapis.com
에서 호스팅되는 Google API입니다. 요청 자체에 OIDC 또는 OAuth를 지정합니다.
다음 예시에서는 작업 요청을 만들며, 헤더 토큰 생성도 포함됩니다. 여기에서는 OIDC 토큰을 사용합니다. OAuth 토큰을 사용하려면 요청을 작성할 때 OIDC 매개변수를 언어에 적합한 OAuth 매개변수로 바꾸세요.
Python
requirements.txt
파일을 확인합니다.
자바
pom.xml
파일을 확인합니다.
Go
Node.js
package.json
파일을 확인합니다.
자체 HTTP Target 태스크 핸들러 제공
HTTP Target 태스크 핸들러는 App Engine 태스크 핸들러와 매우 비슷하지만 다음과 같은 차이점이 있습니다.
- 제한 시간: 모든 HTTP Target 작업 핸들러의 기본 제한 시간은 10분이며 최대 30분까지 가능합니다.
- 인증 로직: 대상 서비스에서 토큰을 검증하는 코드를 직접 작성하는 경우 OIDC 토큰을 사용해야 합니다. 이와 관련된 자세한 내용은 OpenID Connect, 특히 ID 토큰 검증을 참조하세요.
헤더: HTTP Target 요청에 핸들러가 사용할 수 있는 작업별 정보가 포함된 큐에 의해 설정된 헤더가 있습니다. 이는 App Engine 작업 요청에 설정된 헤더와 유사하지만 동일하지는 않습니다. 이 헤더는 정보만 제공합니다. ID 소스로 사용하면 안 됩니다.
앱에 대한 외부 사용자 요청에 이러한 헤더가 있는 경우 내부 헤더로 대체됩니다. 테스트용 헤더를 설정할 수 있는 로그인한 애플리케이션 관리자가 보내는 요청만이 유일한 예외입니다.
HTTP Target 요청에는 항상 다음 헤더가 포함됩니다.
헤더 설명 X-CloudTasks-QueueName
대기열 이름입니다. X-CloudTasks-TaskName
작업의 '짧은' 이름입니다. 그러나 만들 때 이름이 지정되지 않은 경우에는 시스템에서 생성된 고유한 ID입니다. 이것은 완전한 작업 이름의 my-task-id
값입니다. 즉, task_name =projects/my-project-id/locations/my-location/queues/my-queue-id/tasks/my-task-id
.X-CloudTasks-TaskRetryCount
이 작업이 다시 시도된 횟수입니다. 첫 시도의 경우, 이 값은 0
입니다. 이 숫자에는 5XX 오류 코드로 인해 작업이 실패하고 실행 단계에 도달하지 못한 시도도 포함됩니다.X-CloudTasks-TaskExecutionCount
작업이 핸들러로부터 응답을 받은 총 횟수입니다. Cloud Tasks가 성공적인 응답을 받으면 작업을 삭제하므로 이전의 모든 핸들러 응답은 실패였습니다. 5XX 오류 코드로 인한 실패는 이 숫자에 포함되지 않습니다. X-CloudTasks-TaskETA
작업의 예약 시간으로, 1970년 1월 1일부터의 경과 시간(초)으로 지정됩니다. 또한 Cloud Tasks의 요청에는 다음 헤더가 포함될 수 있습니다.
헤더 설명 X-CloudTasks-TaskPreviousResponse
지난번 재시도에서 나온 HTTP 응답 코드입니다. X-CloudTasks-TaskRetryReason
작업을 다시 시도하는 이유입니다.
Cloud Tasks 서비스 계정에 Cloud Tasks 서비스 에이전트 역할을 수동으로 추가
이 작업은 Cloud Tasks API를 2019년 3월 19일 이전에 사용 설정한 경우에만 필요합니다.
Console 사용
- Google Cloud 프로젝트 설정 페이지에서 프로젝트의 프로젝트 번호를 찾습니다.
- 번호를 복사해 둡니다.
- IAM 관리 콘솔 페이지를 엽니다.
Add
를 클릭합니다.Add members
화면이 열립니다.새 구성원 대화상자에 이메일 주소를 다음 형식으로 추가합니다.
service-[project-number]@gcp-sa-cloudtasks.iam.gserviceaccount.com
[project-number]를 위에서 확인한 프로젝트 번호로 바꿉니다.
Select a role
드롭다운에서Service Management
->Cloud Tasks Service Agent
를 선택합니다.Save
를 클릭합니다.
gcloud 사용
프로젝트 번호를 찾습니다.
gcloud projects describe [project-id] --format='table(projectNumber)'
[project-id]를 프로젝트 ID로 바꿉니다.
번호를 복사해 둡니다.
복사한 프로젝트 번호를 사용하여 Cloud Tasks 서비스 계정에
Cloud Tasks Service Agent
역할을 부여합니다.gcloud projects add-iam-policy-binding [project-id] --member serviceAccount:service-[project-number]@gcp-sa-cloudtasks.iam.gserviceaccount.com --role roles/cloudtasks.serviceAgent
[project-id]를 프로젝트 ID로 바꾸고 [project-number]를 위의 프로젝트 번호로 바꿉니다.
다음 단계
- RPC API 참조에서 HTTP 대상 작업에 대해 자세히 알아보기
- REST API 참조에서 HTTP Target 작업에 대해 자세히 알아보기.