사용자 정의 함수 (UDF) 개요

JavaScript 사용자 정의 함수 (UDF)는 단일 메시지 변환 (SMT)의 한 유형입니다. UDF는 BigQuery JavaScript UDF와 마찬가지로 Pub/Sub 내에서 맞춤 변환 로직을 구현하는 유연한 방법을 제공합니다.

UDF는 단일 메시지를 입력으로 받아 입력에 정의된 작업을 수행하고 프로세스의 결과를 반환합니다.

UDF에는 다음과 같은 주요 속성이 있습니다.

  • 함수 이름: 제공된 코드 내에서 Pub/Sub이 메시지에 적용하는 JavaScript 함수의 이름입니다.

  • 코드: 변환 로직을 정의하는 JavaScript 코드입니다. 이 코드에는 다음 서명이 있는 함수가 포함되어야 합니다.

    /**
* Transforms a Pub/Sub message.
* @return {(Object<string, (string | Object<string, string>)>|* null)} - To
* filter a message, return `null`. To transform a message, return a map with
* the following keys:
*   - (required) 'data' : {string}
*   - (optional) 'attributes' : {Object<string, string>}
* Returning empty `attributes` will remove all attributes from the message.
*
* @param  {(Object<string, (string | Object<string, string>)>} - Pub/Sub
* message. Keys:
*   - (required) 'data' : {string}
*   - (required) 'attributes' : {Object<string, string>}
*
* @param  {Object<string, any>} metadata - Pub/Sub message metadata.
* Keys:
*   - (optional) 'message_id'  : {string}
*   - (optional) 'publish_time': {string} YYYY-MM-DDTHH:MM:SSZ format
*   - (optional) 'ordering_key': {string}
*/
function <function_name>(message, metadata) {
  // Perform custom transformation logic
  return message; // to filter a message instead, return `null`
}

입력

  • message 인수: Pub/Sub 메시지를 나타내는 JavaScript 객체입니다. 여기에는 다음 속성이 포함됩니다.

    • data: (String, 필수) 메시지 페이로드입니다.

    • attributes: (Object<String, String>, 선택사항) 메시지 속성을 나타내는 키-값 쌍의 맵입니다.

  • metadata 인수: Pub/Sub 메시지에 관한 변경 불가능한 메타데이터를 포함하는 JavaScript 객체입니다.

    • message_id: (String, 선택사항) 메시지의 고유 ID입니다.

    • publish_time: (String, 선택사항) 메시지의 게시 시간입니다. RFC 3339 형식 (YYYY-MM-DDTHH:mm:ssZ)입니다.

    • ordering_key: (String, 선택사항) 메시지의 순서 키입니다(해당하는 경우).

출력

  • 메시지를 변환하려면 message.data 및 message.attributes의 콘텐츠를 수정하고 변경된 message 객체를 반환합니다.

  • 메시지를 필터링하려면 null를 반환합니다.

UDF가 메시지를 변환하는 방식

메일에서 UDF를 실행한 결과는 다음 중 하나일 수 있습니다.

  • UDF는 메시지를 변환합니다.

  • UDF는 null를 반환합니다.

    • 주제 SMT: Pub/Sub가 게시자에게 성공을 반환하고 필터링된 메시지의 응답에 메시지 ID를 포함합니다. Pub/Sub는 메시지를 저장하거나 구독자에게 전송하지 않습니다.

    • 구독 SMT: Pub/Sub가 구독자에게 메시지를 전송하지 않고 메시지 전송을 확인합니다.

  • UDF에서 오류가 발생합니다.

    • 주제 SMT: Pub/Sub가 게시자에게 오류를 반환하고 메시지를 게시하지 않습니다.

    • 구독 SMT: Pub/Sub가 메시지를 부정적으로 확인합니다.

제한사항

Pub/Sub은 효율적인 변환 작업을 위해 UDF에 리소스 한도를 적용합니다. 제한사항은 다음과 같습니다.

  • UDF당 최대 20KB의 코드
  • 메시지당 최대 500ms의 실행 시간
  • ECMAScript 표준 내장만 지원
  • 외부 API 호출 없음
  • 외부 라이브러리 가져오기 없음

샘플 UDF

다음은 게시 및 구독을 위한 몇 가지 샘플 UDF입니다.

함수: 요일 정수를 해당 문자열로 변환

다음 UDF를 주제 또는 구독에 추가하면 메시지 게시 또는 전송 중에 다음과 같은 변경사항이 발생합니다.

  1. Pub/Sub가 메시지에 함수를 적용합니다. 메시지에 JSON 페이로드가 없으면 UDF에서 오류가 발생합니다.

  2. UDF는 dayOfWeek이라는 필드를 찾고 이 필드의 값이 0~6 사이의 숫자이면 Monday과 같은 해당 요일로 변환합니다. 필드가 없거나 숫자가 0~6 범위에 없으면 코드는 dayOfWeek 필드를 Unknown로 설정합니다.

  3. UDF는 수정된 페이로드를 메시지로 다시 직렬화합니다.

  4. Pub/Sub은 업데이트된 메시지를 파이프라인의 다음 단계로 전달합니다.

function intToString(message, metadata) {
  const data = JSON.parse(message.data);
  switch(`data["dayOfWeek"]`) {
    case 0:
      data["dayOfWeek"] = "Sunday";
      break;
    case 1:
      data["dayOfWeek"] = "Monday";
      break;
    case 2:
      data["dayOfWeek"] = "Tuesday";
      break;
    case 3:
      data["dayOfWeek"] = "Wednesday";
      break;
    case 4:
      data["dayOfWeek"] = "Thursday";
      break;
    case 5:
      data["dayOfWeek"] = "Friday";
      break;
    case 6:
      data["dayOfWeek"] = "Saturday";
      break;
    default:
      data["dayOfWeek"] = "Unknown";
  }
  message.data = JSON.stringify(data);
  return message;
}

기능: 주민등록번호 수정

다음 UDF를 주제 또는 구독에 추가하면 메시지 게시 또는 전송 중에 다음과 같은 변경사항이 발생합니다.

  1. Pub/Sub가 메시지에 함수를 적용합니다. 메시지에 JSON 페이로드가 없으면 UDF에서 오류가 발생합니다.

  2. UDF는 메시지 페이로드에서 ssn 필드를 삭제합니다 (있는 경우).

  3. UDF는 수정된 페이로드를 메시지로 다시 직렬화합니다.

  4. Pub/Sub은 업데이트된 메시지를 파이프라인의 다음 단계로 전달합니다.

function redactSSN(message, metadata) {
  const data = JSON.parse(message.data);
  delete data['ssn'];
  message.data = JSON.stringify(data);
  return message;
}

기능: 특정 메시지 필터링 및 자동 승인

다음 UDF를 주제 또는 구독에 추가하면 메시지 게시 또는 전송 중에 다음과 같은 변경사항이 발생합니다.

  1. Pub/Sub가 메시지에 함수를 적용합니다. 메시지에 JSON 페이로드가 없으면 UDF에서 오류가 발생합니다.

  2. UDF는 페이로드에 region이라는 필드가 포함되어 있는지 확인합니다.

  3. region 필드 값이 US이 아니면 함수는 null을 반환하여 Pub/Sub가 메시지를 필터링하도록 합니다.

  4. region 필드 값이 US이면 Pub/Sub에서 파이프라인의 다음 단계로 원본 메시지를 전달합니다.

function filterForUSRegion(message, metadata) {
  const data = JSON.parse(message.data);
  if (data["region"] !== "US") {
    return null;
  }
  return message;
}

함수: 금액이 100을 초과하지 않도록 메시지 콘텐츠의 유효성을 검사합니다.

다음 UDF를 주제 또는 구독에 추가하면 메시지 게시 또는 전송 중에 다음과 같은 변경사항이 발생합니다.

  1. Pub/Sub가 메시지에 함수를 적용합니다. 메시지에 JSON 페이로드가 없으면 UDF에서 오류가 발생합니다.

  2. UDF는 메시지에 amount이라는 필드가 포함되어 있는지 확인합니다.

  3. amount 필드 값이 100보다 크면 함수에서 오류가 발생합니다.

  4. amount 필드의 값이 100보다 크지 않으면 함수는 원래 메시지를 반환합니다.

  5. 그런 다음 Pub/Sub은 메시지를 실패로 표시하거나 파이프라인의 다음 단계로 원래 메시지를 전달합니다.

function validateAmount(message, metadata) {
  const data = JSON.parse(message.data);
  if (data["amount"] > 100) {
    throw new Error("Amount is invalid");
  }
  return message;
}

다음 단계