サービス Webhook の構成

新しい Webhook を設定する

受信する Webhook の範囲は個々のサービスに限定されます。 App Services UI の関連するサービス ページから Webhook を作成および管理できます。

受信 Webhook を作成するには、次の手順に従います。

1. 左側のナビゲーション メニューで [ Servicesをクリックします。

2. 受信 Webhook を追加するサービスをクリックします。

3. サービスの [ Incoming Webhooks ] タブを選択します。

4. [ Add Incoming Webhookをクリックします。 App Services は新しい Webhook のSettings画面にリダイレクトします。

新しい Webhook に名前を付ける

Webhook Nameフィールドに Webhook を識別できる一意の名前を入力します。 この名前は、サービス用に作成した他の Webhook と異なる必要があります。

ユーザー認証の設定

Webhook を含む Atlas 関数は常に特定のアプリケーションユーザーのコンテキストで、またはシステムユーザーとして実行され、ルールをバイパスします。 Webhook の実行ユーザーを構成するには、App Services が Webhook に使用する認証のタイプを指定します。

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

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

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

クリックして拡大します

Webhook の HTTP メソッドを選択する

受信リクエストで特定の HTTPメソッドhttpMethod を使用するよう要求するか、コンテキストの プロパティを検査することで、すべてのHTTPメソッドを受け入れ、Webhook 関数でそれぞれを個別に処理することができます。次の例関数のように、オブジェクトをリクエスト。

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 応答の構成

Webhook を呼び出す外部サービスに、構成可能なHTTPレスポンス を送信できます。

Respond With Result を有効にすると、Webhook は基本的なHTTP 200 応答で受信リクエストに応答します。この応答には Webhook 関数の戻り値が bodyフィールドとして含まれます。App Services が 2 番目の引数として自動的に渡す responseオブジェクトを使用して、Webhook 関数内からカスタムHTTPレスポンスを構成できます。

クリックして拡大します

承認式の指定

Can Evaluate式を定義することで、各リクエストの内容に基づいてリクエストを動的に承認できます。Atlas App Services は、Webhook が受信するすべての受信リクエストに対して式を評価します。 式を指定しない場合、Atlas App Services は認証されたすべての受信リクエストを自動的に承認します。

式は、 の展開を含む標準の 式変数 %%requestを展開できます。

クリックして拡大します

リクエスト検証方法の指定

Webhook リクエストが信頼できるソースから送信されたことを検証するために、一部の外部サービスでは、受信リクエストにいくつかの方法で秘密の string を含める必要があります。 HTTP Serviceなどの他のサービスでは、オプションでリクエスト検証を要求できます。

Webhook にリクエスト検証が必要な場合は、次のようにします。

1. リクエスト検証方法を選択します。

2. リクエスト検証プロセスで使用するSecret string を入力します。

クリックして拡大します

Webhook 関数の記述

Webhook を構成したら、残りは Webhook を呼び出したときに実行される関数を書込むだけです。 App Services は、Webhook 関数の引数として 2 つのオブジェクトを自動的に渡します。

次の Webhook 関数を、独自の 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 を保存する

Webhook への変更は、有効になる前に保存する必要があります。 そのためには、 Settings画面またはFunction EditorからSaveをクリックします。

アプリの最新バージョンを取得する

realm-cliを使用して受信 Webhook を定義するには、アプリケーションの構成ファイルのローカル コピーが必要です。

アプリの最新バージョンのローカルコピーを取得するには、次のコマンドを実行します。

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

Webhook 構成ディレクトリの追加

/http_endpoints/<service>/incoming_webhooks/の Webhook と同じ名前で新しいサブディレクトリを作成します。

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

Webhook 構成ファイルの追加

config.jsonという名前の受信 Webhook 構成ファイルを新しい Webhook ディレクトリに追加します。

構成ファイルは、次の形式である必要があります。

{
  "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フィールドに Webhook の名前を入力します。 この名前は、サービス用に作成した他の Webhook と異なる必要があります。

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

ユーザー認証の設定

App Services が Webhook に使用する認証の種類を指定します。 App Services は次の Webhook 認証方法をサポートしています。

{
  "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メソッドを使用するよう要求するか、コンテキストの httpMethodプロパティを検査することで、すべてのHTTPメソッドを受け入れ、Webhook 関数でそれぞれを個別に処理することができます。次の例関数のように、オブジェクトをリクエスト。

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 メソッドを指定するには、すべて大文字を使用してメソッドの名前にoptions.httpMethodフィールドを設定するか、 "ANY"を使用します。

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

Webhook 応答の構成

Webhook を呼び出す外部サービスに、構成可能なHTTPレスポンス を送信できます。受信リクエストに応答を送信するように Webhook を構成するには、respond_result を true に設定します。

Respond With Result を有効にすると、Webhook は基本的なHTTP 200 応答で受信リクエストに応答します。この応答には Webhook 関数の戻り値が bodyフィールドとして含まれます。App Services が 2 番目の引数として自動的に渡す responseオブジェクトを使用して、Webhook 関数内からカスタムHTTPレスポンスを構成できます。

承認式の指定

Can Evaluate式を定義することで、各リクエストの内容に基づいてリクエストを動的に認可できます。 Atlas App Services は、Webhook が受け取るすべての受信リクエストに対して式を評価します。 式は、 の展開を含む標準の 式変数 %%requestを展開できます。

認可式を定義するには、 can_evaluateフィールドの値を式に設定します。 式を指定しない場合、Atlas App Services は認証されたすべての受信リクエストを自動的に認可します。

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

リクエスト検証方法の指定

Webhook リクエストが信頼できるソースから送信されたことを検証するために、一部の外部サービスでは、受信リクエストにいくつかの方法で秘密の string を含める必要があります。 HTTP Serviceなどの他のサービスでは、オプションでリクエスト検証を要求できます。

Webhook のリクエスト認証方法は、Webhook 構成のoptionsドキュメントで構成できます。 App Services は次のリクエスト検証メソッドをサポートしています。

{
  "validationMethod": "NO_VALIDATION"
}

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

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

Webhook 関数のソースコードを追加する

source.jsという名前のファイルを新しい Webhook ディレクトリに追加します。 ファイルには、Webhook が呼び出されたときに実行される有効な関数が含まれている必要があります。

App Services は、Webhook 関数の引数として 2 つのオブジェクトを自動的に渡します。

次の Webhook 関数を、独自の 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!" };
};

受信 Webhook 構成の配置

config.jsonでクラスターの読み込み設定（read preference）を設定したら、その設定をリモート アプリにプッシュできます。 App Services CLI はプッシュ時に更新をすぐに配置します。

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