Cloud Tasks를 사용하여 Cloud Run 함수 트리거

이 튜토리얼에서는 App Engine 애플리케이션 내에서 Cloud Tasks를 사용하여 Cloud Run 함수를 트리거하고 예약된 이메일을 보내는 방법을 다룹니다.

코드 이해하기

이 섹션에서는 앱 코드와 코드의 작동 방식을 살펴봅니다.

태스크 만들기

색인 페이지는 app.yaml의 핸들러를 사용하여 제공됩니다. 태스크 생성에 필요한 변수는 환경 변수로 전달됩니다.

runtime: nodejs16

env_variables:
  QUEUE_NAME: "my-queue"
  QUEUE_LOCATION: "us-central1"
  FUNCTION_URL: "https://<region>-<project_id>.cloudfunctions.net/sendEmail"
  SERVICE_ACCOUNT_EMAIL: "<member>@<project_id>.iam.gserviceaccount.com"

# Handlers for serving the index page.
handlers:
  - url: /static
    static_dir: static
  - url: /
    static_files: index.html
    upload: index.html

이 코드는 엔드포인트 /send-email을 생성합니다. 이 엔드포인트는 색인 페이지에서 양식 제출을 처리하고 해당 데이터를 태스크 생성 코드에 전달합니다.

app.post('/send-email', (req, res) => {
  // Set the task payload to the form submission.
  const {to_name, from_name, to_email, date} = req.body;
  const payload = {to_name, from_name, to_email};

  createHttpTaskWithToken(
    process.env.GOOGLE_CLOUD_PROJECT,
    QUEUE_NAME,
    QUEUE_LOCATION,
    FUNCTION_URL,
    SERVICE_ACCOUNT_EMAIL,
    payload,
    date
  );

  res.status(202).send('📫 Your postcard is in the mail! 💌');
});

이 코드는 실제로 태스크를 만들어 Cloud Tasks 큐로 보냅니다. 코드는 다음과 같이 태스크를 빌드합니다.

• 대상 유형을 HTTP Request로 지정

• 사용할 HTTP method와 대상의 URL 지정

• 다운스트림 애플리케이션이 구조화된 페이로드를 파싱할 수 있도록 Content-Type 헤더를 application/json으로 설정

• Cloud Tasks가 인증이 필요한 요청 대상에 사용자 인증 정보를 제공할 수 있도록 서비스 계정 이메일 추가. 서비스 계정은 별도로 생성됩니다.

• 날짜에 대한 사용자 입력이 최대 30일 이내인지 확인하고 이를 필드 scheduleTime으로 요청에 추가

const MAX_SCHEDULE_LIMIT = 30 * 60 * 60 * 24; // Represents 30 days in seconds.

const createHttpTaskWithToken = async function (
  project = 'my-project-id', // Your GCP Project id
  queue = 'my-queue', // Name of your Queue
  location = 'us-central1', // The GCP region of your queue
  url = 'https://example.com/taskhandler', // The full url path that the request will be sent to
  email = '<member>@<project-id>.iam.gserviceaccount.com', // Cloud IAM service account
  payload = 'Hello, World!', // The task HTTP request body
  date = new Date() // Intended date to schedule task
) {
  // Imports the Google Cloud Tasks library.
  const {v2beta3} = require('@google-cloud/tasks');

  // Instantiates a client.
  const client = new v2beta3.CloudTasksClient();

  // Construct the fully qualified queue name.
  const parent = client.queuePath(project, location, queue);

  // Convert message to buffer.
  const convertedPayload = JSON.stringify(payload);
  const body = Buffer.from(convertedPayload).toString('base64');

  const task = {
    httpRequest: {
      httpMethod: 'POST',
      url,
      oidcToken: {
        serviceAccountEmail: email,
        audience: url,
      },
      headers: {
        'Content-Type': 'application/json',
      },
      body,
    },
  };

  const convertedDate = new Date(date);
  const currentDate = new Date();

  // Schedule time can not be in the past.
  if (convertedDate < currentDate) {
    console.error('Scheduled date in the past.');
  } else if (convertedDate > currentDate) {
    const date_diff_in_seconds = (convertedDate - currentDate) / 1000;
    // Restrict schedule time to the 30 day maximum.
    if (date_diff_in_seconds > MAX_SCHEDULE_LIMIT) {
      console.error('Schedule time is over 30 day maximum.');
    }
    // Construct future date in Unix time.
    const date_in_seconds =
      Math.min(date_diff_in_seconds, MAX_SCHEDULE_LIMIT) + Date.now() / 1000;
    // Add schedule time to request in Unix time using Timestamp structure.
    // https://googleapis.dev/nodejs/tasks/latest/google.protobuf.html#.Timestamp
    task.scheduleTime = {
      seconds: date_in_seconds,
    };
  }

  try {
    // Send create task request.
    const [response] = await client.createTask({parent, task});
    console.log(`Created task ${response.name}`);
    return response.name;
  } catch (error) {
    // Construct error for Stackdriver Error Reporting
    console.error(Error(error.message));
  }
};

module.exports = createHttpTaskWithToken;

이메일 만들기

이 코드는 Cloud Tasks 요청의 대상인 Cloud Run 함수를 만듭니다. 또한 요청 본문을 사용하여 이메일을 작성하고 SendGrid API를 통해 보냅니다.

const sendgrid = require('@sendgrid/mail');

/**
 * Responds to an HTTP request from Cloud Tasks and sends an email using data
 * from the request body.
 *
 * @param {object} req Cloud Function request context.
 * @param {object} req.body The request payload.
 * @param {string} req.body.to_email Email address of the recipient.
 * @param {string} req.body.to_name Name of the recipient.
 * @param {string} req.body.from_name Name of the sender.
 * @param {object} res Cloud Function response context.
 */
exports.sendEmail = async (req, res) => {
  // Get the SendGrid API key from the environment variable.
  const key = process.env.SENDGRID_API_KEY;
  if (!key) {
    const error = new Error(
      'SENDGRID_API_KEY was not provided as environment variable.'
    );
    error.code = 401;
    throw error;
  }
  sendgrid.setApiKey(key);

  // Get the body from the Cloud Task request.
  const {to_email, to_name, from_name} = req.body;
  if (!to_email) {
    const error = new Error('Email address not provided.');
    error.code = 400;
    throw error;
  } else if (!to_name) {
    const error = new Error('Recipient name not provided.');
    error.code = 400;
    throw error;
  } else if (!from_name) {
    const error = new Error('Sender name not provided.');
    error.code = 400;
    throw error;
  }

  // Construct the email request.
  const msg = {
    to: to_email,
    from: '[e-mail]',
    subject: 'A Postcard Just for You!',
    html: postcardHTML(to_name, from_name),
  };

  try {
    await sendgrid.send(msg);
    // Send OK to Cloud Task queue to delete task.
    res.status(200).send('Postcard Sent!');
  } catch (error) {
    // Any status code other than 2xx or 503 will trigger the task to retry.
    res.status(error.code).send(error.message);
  }
};

애플리케이션 준비

SendGrid 설정

1. SendGrid 계정 만들기

   • SendGrid 웹 사이트를 통해 수동으로 만들거나
   • Google Cloud Launcher를 사용하여 계정을 만들고 결제를 통합할 수 있습니다. Cloud Launcher를 사용하여 SendGrid 계정 만들기를 참조하세요.

2. SendGrid API 키를 만듭니다.

   1. SendGrid 계정에 로그인합니다.

   2. 왼쪽 탐색 메뉴에서 설정을 열고 API 키를 클릭합니다.

   3. API 키 만들기를 클릭하고 제한된 액세스를 선택합니다. Mail Send 헤더에서 전체 액세스를 선택합니다.

   4. API 키가 표시되면 복사합니다. 이 키는 한 번만 표시되므로 나중에 사용할 수 있도록 어딘가에 붙여넣기 해 두세요.

소스 코드 다운로드

1. 샘플 앱 저장소를 로컬 머신에 클론합니다.

   git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
   

2. 샘플 코드가 있는 디렉터리로 변경합니다.

   cd cloud-tasks/
   

Cloud Run 함수 배포

1. function/ 디렉터리로 이동합니다.

   cd function/
   

2. 함수를 배포합니다.

   gcloud functions deploy sendEmail --runtime nodejs14 --trigger-http \
     --no-allow-unauthenticated \
     --set-env-vars SENDGRID_API_KEY=SENDGRID_API_KEY \

   SENDGRID_API_KEY를 내 API 키로 바꿉니다.

   이 명령어는 다음 플래그를 사용합니다.

   • --trigger-http를 사용하여 Cloud Run 함수 트리거 유형 지정

   • --no-allow-unauthenticated를 사용하여 인증이 필요한 함수 호출 지정

   • --set-env-var를 사용하여 SendGrid 사용자 인증 정보 설정

   참고: Firebase 및 Google Cloud 콘솔 모두에서 Cloud Run 함수를 관리할 수 있습니다. FirebaseUI에서 쓰기 및 배포는 복제될 수 있지만, 함수 코드가 Firebase Functions 프레임워크와 일치해야 합니다. Firebase 함수 및 HTTP 트리거 시작하기에 대해 자세히 알아보세요.

3. 인증된 사용자만 허용하도록 함수의 액세스 제어를 설정합니다.

   1. Cloud Run 함수 UI에서 sendEmail 함수를 선택합니다.

   2. sendEmail에 대해 권한 정보가 표시되지 않으면 오른쪽 위 모서리에서 정보 패널 표시를 클릭합니다.

   3. 위의 주 구성원 추가 버튼을 클릭합니다.

   4. 새 주 구성원을 allAuthenticatedUsers로 설정합니다.

   5. 역할을 설정합니다.

      • 1세대 함수: 역할을 Cloud Function Invoker로 설정
      • 2세대 함수: 역할을 Cloud Run Invoker로 설정

   6. 저장을 클릭합니다.

Cloud Tasks 큐 만들기

1. 다음 gcloud 명령어를 사용하여 큐를 만듭니다.

   gcloud tasks queues create my-queue --location=LOCATION

   LOCATION을 큐의 선호하는 위치(예: us-west2)로 바꿉니다. 위치를 지정하지 않으면 gcloud CLI에서 기본값을 선택합니다.

2. 성공적으로 생성되었는지 확인합니다.

   gcloud tasks queues describe my-queue --location=LOCATION

   LOCATION을 큐의 위치로 바꿉니다.

서비스 계정 만들기

Cloud Tasks 요청은 Cloud Run 함수가 요청을 인증할 수 있도록 Authorization 헤더에 사용자 인증 정보를 제공해야 합니다. 이 서비스 계정을 사용하면 Cloud Tasks에서 이러한 목적으로 OIDC 토큰을 만들고 추가할 수 있습니다.

1. 서비스 계정 UI에서 +서비스 계정 만들기를 클릭합니다.

2. 서비스 계정 이름(알기 쉬운 표시 이름)을 추가하고 만들기를 선택합니다.

3. 역할을 설정하고 계속을 클릭합니다.

   • 1세대 함수: 역할을 Cloud Function Invoker로 설정
   • 2세대 함수: 역할을 Cloud Run Invoker로 설정

4. 완료를 선택합니다.

엔드포인트 및 태스크 생성자를 App Engine에 배포

1. app/ 디렉터리로 이동합니다.

   cd ../app/
   

2. app.yaml의 변수를 다음 값으로 업데이트합니다.

   env_variables:
     QUEUE_NAME: "my-queue"
     QUEUE_LOCATION: "us-central1"
     FUNCTION_URL: "https://<region>-<project_id>.cloudfunctions.net/sendEmail"
     SERVICE_ACCOUNT_EMAIL: "<member>@<project_id>.iam.gserviceaccount.com"

   큐 위치를 찾으려면 다음 명령어를 사용합니다.

   gcloud tasks queues describe my-queue --location=LOCATION

   LOCATION을 큐의 위치로 바꿉니다.

   함수 URL을 찾으려면 다음 명령어를 사용합니다.

   gcloud functions describe sendEmail

3. 다음 명령어를 사용하여 App Engine 표준 환경에 애플리케이션을 배포합니다.

   gcloud app deploy

4. 애플리케이션을 열어 이메일로 엽서를 보냅니다.

   gcloud app browse