서비스 Webhooks 구성 [사용 중단됨]

새 Webhook 설정

수신 웹훅의 범위는 개별 서비스 로 할당됩니다. App Services UI의 연결된 서비스 페이지에서 웹훅을 만들고 관리할 수 있습니다.

수신 웹훅을 만들려면 다음과 같이 합니다:

1. 왼쪽 탐색 패널에서 Services 을 클릭합니다.

2. 수신 웹훅을 추가할 서비스를 클릭합니다.

3. 서비스에 대한 Incoming Webhooks 탭을 선택합니다.

4. Add Incoming Webhook를 클릭합니다. App Services는 새 웹훅에 대한 Settings 화면으로 리디렉션합니다.

새 Webhook 이름 지정

Webhook Name 필드에 함수를 식별할 수 있는 고유한 이름을 입력합니다. 이 이름은 서비스에 대해 생성한 다른 웹훅과 구별되어야 합니다.

사용자 인증 구성

웹훅을 비롯한 Atlas Functions는 항상 특정 애플리케이션 사용자의 컨텍스트에서 또는 규칙을 우회하는 시스템 사용자로서 실행됩니다. 웹훅의 실행 사용자를 구성하려면 App Services에서 웹훅에 사용해야 하는 인증 유형을 지정합니다.

{
  "email": "<User's Email Address>",
  "password": "<User's Password>"
}

{
  "api-key": "<User's API Key>"
}

{
  "jwtTokenString": "<User's JWT Token>"
}

클릭하여 확대

Webhook의 HTTP 메서드 선택

수신 요청이 특정 HTTP 메서드 를 사용하도록 요구할 수 있습니다. 또는 모든 HTTP 메서드를 허용하고 웹훅 함수에서 httpMethod 컨텍스트 의 속성 을 검사하여 각 메서드를 개별적으로 처리하다 할 수 있습니다. 다음 예시 함수에서와 같이 객체 를 요청 합니다.

exports = function(payload, response) {
  switch(context.request.httpMethod) {
    case "GET": { /* Handle GET requests */ }
    case "POST": { /* Handle POST requests */ }
    case "PUT": { /* Handle PUT requests */ }
    case "DELETE": { /* Handle DELETE requests */ }
    case "PATCH": { /* Handle PATCH requests */ }
    default: {}
  }
}

Webhook 응답 구성

구성 가능한 HTTP 응답 을 보낼 수 있습니다. 웹훅을 호출하는 외부 서비스에 연결합니다.

Respond With Result을(를) 활성화하면 웹훅이 수신 요청에 대해 웹훅 함수 반환 값을 body 필드로 포함하는 기본 HTTP 200 응답으로 응답합니다. App Services가 자동으로 두 번째 인수로 전달하는 response 객체를 사용하여 웹훅 함수 내에서 사용자 지정 HTTP 응답을 구성할 수 있습니다.

클릭하여 확대

권한 부여 표현식 지정하기

Can Evaluate표현식을 정의하여 각 요청의 내용에 따라 요청을 동적으로 승인할 수 있습니다. App Services는 웹훅이 수신하는 모든 수신 요청에 대한 식을 평가합니다. 표현식을 지정하지 않으면 App Services는 인증된 모든 수신 요청에 자동으로 권한을 부여합니다.

이 표현식은 %%request의 확장을 포함한 표준 표현식 변수를 확장할 수 있습니다.

클릭하여 확대

요청 유효성 검사 메서드 지정

웹훅 요청이 신뢰할 수 있는 출처에서 전송되었는지 확인하기 위해 일부 외부 서비스에서는 들어오는 요청에 몇 가지 규정된 방식 중 하나로 비밀 문자열을 통합하도록 요구합니다. HTTP 서비스와 같은 다른 서비스에서는 선택적으로 요청 유효성 검사(request validation)를 요구할 수 있습니다.

웹훅에 요청 유효성 검사가 필요한 경우:

1. 요청 유효성 검사 방법을 선택합니다.

2. 요청 유효성 검사 프로세스에서 사용할 Secret 문자열을 입력합니다.

클릭하여 확대

Webhook 함수 작성

웹훅을 설정한 후에는 웹훅을 호출할 때 실행되는 함수를 작성하는 것만 남았습니다. 앱 서비스는 웹훅 함수의 인수로 두 개의 객체를 자동으로 전달합니다:

다음 웹훅 기능을 자체 웹훅의 기반으로 사용할 수 있습니다.

exports = async function (payload, response) {
  // Convert the webhook body from BSON to an EJSON object
  const body = EJSON.parse(payload.body.text());
  // Execute application logic, such as working with MongoDB
  if (body.someField) {
    const mdb = context.services.get("mongodb-atlas");
    const requests = mdb.db("demo").collection("requests");
    const { insertedId } = await requests.insertOne({
      someField: body.someField,
    });
    // Respond with an affirmative result
    response.setStatusCode(200);
    response.setBody(`Successfully saved "someField" with _id: ${insertedId}.`);
  } else {
    // Respond with a malformed request error
    response.setStatusCode(400);
    response.setBody(`Could not find "someField" in the webhook request body.`);
  }
  // This return value does nothing because we already modified the response object.
  // If you do not modify the response object and you enable *Respond with Result*,
  // App Services will include this return value as the response body.
  return { msg: "finished!" };
};

exports(
  { body: "This document is the webhook payload" },
  new HTTPResponse()
)

Webhook 저장

변경 사항이 적용되기 전에 웹훅에 대한 변경 사항을 저장해야 합니다. 이렇게 하려면 Settings 화면 또는 Function Editor에서 Save 을 클릭합니다.

앱의 최신 버전 가져오기

realm-cli 를 사용하여 수신 웹훅을 정의하려면 애플리케이션 구성 파일의 로컬 복사본이 필요합니다.

최신 버전의 앱의 로컬 사본을 가져오려면 다음을 실행하세요.

realm-cli pull --remote="<Your App ID>"

Webhook 구성 디렉토리 추가

/http_endpoints/<service>/incoming_webhooks/ 에서 웹훅과 동일한 이름으로 새 하위 디렉토리를 생성합니다.

mkdir -p http_endpoints/<service>/incoming_webhooks/<webhook name>

Webhook 구성 파일 추가

config.json 라는 이름의 수신 웹훅 구성 파일 을 새 웹훅 디렉토리 에 추가합니다.

구성 파일 의 형식은 다음과 같아야 합니다.

{
  "name": "<Webhook Name>",
  "can_evaluate": { <JSON Expression> },
  "run_as_authed_user": <Boolean>,
  "run_as_user_id": "<App Services User ID>",
  "run_as_user_id_script_source": "<Function Source Code>",
  "respond_result": <Boolean>,
  "fetch_custom_user_data": <Boolean>,
  "create_user_on_auth": <Boolean>,
  "options": {
    "httpMethod": "<HTTP Method>",
    "validationMethod": "<Webhook Validation Method>",
    "secret": "<Webhook Secret>"
  }
}

새 Webhook 이름 지정

구성 파일의 name 필드 에 웹훅의 이름을 입력합니다. 이 이름은 서비스에 대해 생성한 다른 웹훅과 구별되어야 합니다.

{
  "name": "<Unique Webhook Name>"
}

사용자 인증 구성

App Services 가 웹훅에 사용해야 하는 인증 유형을 지정합니다. App Services 는 다음과 같은 웹훅 인증 방법을 지원합니다.

{
  "run_as_authed_user": true,
  "run_as_user_id": "",
  "run_as_user_id_script_source": "",
}

{
  "email": "<User's Email Address>",
  "password": "<User's Password>"
}

{
  "api-key": "<User's API Key>"
}

{
  "jwtTokenString": "<User's JWT Token>"
}

{
  "run_as_authed_user": false,
  "run_as_user_id": "",
  "run_as_user_id_script_source": "",
}

{
  "run_as_authed_user": false,
  "run_as_user_id": "<App Services User ID>",
  "run_as_user_id_script_source": "",
}

{
  "run_as_authed_user": false,
  "run_as_user_id": "",
  "run_as_user_id_script_source": "<Stringified Function>",
}

Webhook의 HTTP 메서드 지정

수신 요청이 특정 HTTP 메서드 를 사용하도록 요구할 수 있습니다. 또는 모든 HTTP 메서드를 허용하고 웹훅 함수에서 httpMethod 컨텍스트 의 속성 을 검사하여 각 메서드를 개별적으로 처리하다 할 수 있습니다. 다음 예시 함수에서와 같이 객체 를 요청 합니다.

exports = function(payload, response) {
  switch(context.request.httpMethod) {
    case "GET": { /* Handle GET requests */ }
    case "POST": { /* Handle POST requests */ }
    case "PUT": { /* Handle PUT requests */ }
    case "DELETE": { /* Handle DELETE requests */ }
    case "PATCH": { /* Handle PATCH requests */ }
    default: {}
  }
}

웹훅 메서드를 설정하다 하려면 options.httpMethod 필드 를 모두 대문자 또는 "ANY" 를 사용하여 메서드 이름으로 설정합니다.

{
  "options": {
    "httpMethod": "POST"
  }
}

Webhook 응답 구성

구성 가능한 HTTP 응답 을 보낼 수 있습니다. 웹훅을 호출하는 외부 서비스에 연결합니다. 들어오는 요청에 대한 응답을 보내도록 웹훅을 구성하려면 respond_result 를 true 로 설정하다 합니다.

Respond With Result을(를) 활성화하면 웹훅이 수신 요청에 대해 웹훅 함수 반환 값을 body 필드로 포함하는 기본 HTTP 200 응답으로 응답합니다. App Services가 자동으로 두 번째 인수로 전달하는 response 객체를 사용하여 웹훅 함수 내에서 사용자 지정 HTTP 응답을 구성할 수 있습니다.

권한 부여 표현식 지정하기

Can Evaluate 표현식 을 정의하여 각 요청 의 내용을 기반으로 요청에 동적으로 권한을 부여할 수 있습니다. App Services 는 웹훅이 수신하는 모든 수신 요청 에 대한 표현식 을 평가합니다. 표현식 은 확장 %%request 을 포함한 표준 표현식 변수 를 확장할 수 있습니다.

권한 부여 표현식 을 정의하려면 can_evaluate 필드 값을 표현식 으로 설정하다 합니다. 표현식 을 지정하지 않으면 App Services 는 인증된 모든 수신 요청에 자동으로 권한을 부여합니다.

{
    "%%request.remoteIPAddress": {
        "$nin": [
            "248.88.57.58",
            "19.241.23.116",
            "147.64.232.1"
        ]
    }
}

요청 유효성 검사 메서드 지정

웹훅 요청이 신뢰할 수 있는 출처에서 전송되었는지 확인하기 위해 일부 외부 서비스에서는 들어오는 요청에 몇 가지 규정된 방식 중 하나로 비밀 문자열을 통합하도록 요구합니다. HTTP 서비스와 같은 다른 서비스에서는 선택적으로 요청 유효성 검사(request validation)를 요구할 수 있습니다.

웹훅 구성의 options 문서 에서 웹훅의 요청 권한 부여 방법을 구성할 수 있습니다. App Services 는 다음과 같은 요청 유효성 검사 메서드를 지원합니다.

{
  "validationMethod": "NO_VALIDATION"
}

{
  "validationMethod": "VERIFY_PAYLOAD",
  "secret": "<Secret Value>"
}

{
  "validationMethod": "SECRET_AS_QUERY_PARAM",
  "secret": "<Secret Value>"
}

Webhook 함수 소스 코드 추가

새 웹훅 디렉토리 에 source.js 라는 파일 을 추가합니다. 파일 에는 웹훅이 호출될 때 실행되는 유효한 함수가 포함되어 있어야 합니다.

앱 서비스는 웹훅 함수의 인수로 두 개의 객체를 자동으로 전달합니다:

다음 웹훅 기능을 자체 웹훅의 기반으로 사용할 수 있습니다.

exports = async function (payload, response) {
  // Convert the webhook body from BSON to an EJSON object
  const body = EJSON.parse(payload.body.text());
  // Execute application logic, such as working with MongoDB
  if (body.someField) {
    const mdb = context.services.get("mongodb-atlas");
    const requests = mdb.db("demo").collection("requests");
    const { insertedId } = await requests.insertOne({
      someField: body.someField,
    });
    // Respond with an affirmative result
    response.setStatusCode(200);
    response.setBody(`Successfully saved "someField" with _id: ${insertedId}.`);
  } else {
    // Respond with a malformed request error
    response.setStatusCode(400);
    response.setBody(`Could not find "someField" in the webhook request body.`);
  }
  // This return value does nothing because we already modified the response object.
  // If you do not modify the response object and you enable *Respond with Result*,
  // App Services will include this return value as the response body.
  return { msg: "finished!" };
};

수신 Webhook 구성 배포

config.json 에서 클러스터 에 대한 읽기 설정 (read preference) 을 설정하다 한 후에는 구성을 원격 앱 으로 푸시할 수 있습니다. App Services CLI 는 푸시 시 업데이트 를 즉시 배포합니다.

realm-cli push --remote="<Your App ID>"