HTTP エンドポイント構成ファイル

Atlas App Services はサポート終了のステータスに達し、 MongoDBでアクティブにサポートされなくなりました。Atlas UIでは引き続き trigger を利用できます。詳細については、の廃止ページを参照してください。

注意

このページでは、レガシー構成ファイル形式について説明します。非推奨の realm-cliを使用している場合にのみ、この情報を使用する必要があります。

App Services CLI を使用してプルする構成ファイル、または UI からエクスポートする構成ファイルには、最新の構成バージョンが使用されます。現在の構成ファイル形式の詳細については、「アプリ構成」を参照してください。

app/
└── http_endpoints/
    ├── config.json
    ├── data_api_config.json
    └── <Service Name>/
        ├── config.json
        ├── rules/
        │   └── <Rule Name>.json
        └── incoming_webhooks/
            └── <Webhook Name>/
                ├── config.json
                └── source.js

カスタム HTTPS エンドポイント構成

アプリのすべてのカスタムHTTPS endpointsの構成を http_endpoints/config.json の配列として定義します。

[
  {
    "route": "<Endpoint route name>",
    "http_method": "<HTTP method>",
    "function_name": "<Endpoint function name",
    "validation_method": "<Authorization scheme>",
    "secret_name": "<Validation Secret Name>",
    "respond_result": <boolean>,
    "fetch_custom_user_data": <boolean>,
    "create_user_on_auth": <boolean>,
    "disabled": <boolean>
  }
]

フィールド	説明
`route` string	エンドポイントルート。
`http_method` string	エンドポイントが取り扱うHTTPメソッドのタイプ。エンドポイントが 1 つのすべてのメソッドを処理するには、`` を指定します。次の 1 つ： `"GET"` `"POST"` `"PUT"` `"PATCH"` `"DELETE"` `"DELETE"` `""`
`function_name` string	エンドポイントに関連付けられている関数の名前。関数はエンドポイント関数署名を使用する必要があります。
`validation_method` string	受信リクエストを検証するために使用されるエンドポイント認可スキーム。次の 1 つ： `"SECRET_AS_QUERY_PARAM"` `"VERIFY_PAYLOAD"` `"NO_VALIDATION"`
`secret_name` string	string を含むシークレットの名前。 `validation_method`が`SECRET_AS_QUERY_PARAM`または`VERIFY_PAYLOAD`に設定されている場合、このシークレットはリクエストを承認するために使用されます。
`respond_result` boolean	`true`の場合、エンドポイントはクライアントにカスタマイズ可能な HTTP レスポンスを返します。 Responseオブジェクトのメソッドを呼び出すことで、応答を構成します。レスポンスを設定しない場合、エンドポイントはエンドポイント関数から返された値をリクエスト本文として持つ`200 - Ok`レスポンスを返します。 `false`の場合、リクエストは本体にデータを含まない`204 - No Content`応答を返します。
`fetch_custom_user_data` boolean	`true`の場合、認証されたユーザーのカスタムユーザーデータドキュメントは`context.user.custom_data`経由で利用できます。 `false`の場合、ユーザーのカスタムデータはクエリされず、 `context.user.custom_data`は空のオブジェクトです。
`create_user_on_auth` boolean	`true`の場合、提供されたユーザー認証情報が正常に認証され、かつ既存のユーザーに関連付けられていない場合には、アプリは新しいユーザーを自動的に作成します。この設定は、カスタムJSON web token認証プロバイダーを介して外部認証システムと統合するアプリに便利です。リクエストに、登録されているユーザーに対応していない外部システムからの有効なJSON web tokenが含まれている場合、 JSON web tokenを ID として持つ新しいユーザーが作成されます。
`disabled` boolean	エンドポイントを有効にする（ `false` ）または無効にする（ `true` ）。

データ API 構成

アプリで生成されたデータ API エンドポイントの構成をhttp_endpoints/data_api_config.jsonで定義します。

{
  "disabled": <boolean>,
  "versions": ["v1"],
  "return_type": "EJSON" | "JSON",
  "create_user_on_auth": <boolean>,
  "run_as_system": <boolean>,
  "run_as_user_id": "<User Account ID>",
  "run_as_user_id_script_source": "<Function Source Code>"
}

フィールド	説明
`disabled` boolean	`false`の場合、データ API は有効になっていません。生成されたエンドポイントは、リクエストを処理したり応答したりしません。
`versions` string[]	アプリがサポートするデータ API バージョンのリスト。リストには可能なすべてのバージョンのサブセットを含めることができますが、バージョンは昇順で一覧表示する必要があります。最新バージョン以外のバージョンを有効にすることはできませんが、ここにリストされている以前に有効になっているバージョンは引き続き機能します。利用可能なバージョン: `"v1"`
`return_type` string	HTTPS レスポンスボディのエンドポイントによって返されるデータに使用するデータ形式。次の 1 つ： `"EJSON"` `"JSON"`
`create_user_on_auth` boolean	`true`の場合、提供されたユーザー認証情報が正常に認証され、かつ既存のユーザーに関連付けられていない場合には、アプリは新しいユーザーを自動的に作成します。この設定は、カスタムJSON web token認証プロバイダーを介して外部認証システムと統合するアプリに便利です。リクエストに、登録されているユーザーに対応していない外部システムからの有効なJSON web tokenが含まれている場合、 JSON web tokenを ID として持つ新しいユーザーが作成されます。
`run_as_user_id` string	アプリケーションユーザーのアカウントID。定義されている場合、エンドポイントは常に指定されたユーザーとして実行されます。 `run_as_user_id_script_source` とは併用できません。
`run_as_user_id_script_source` string	アプリケーションユーザーのアカウント ID を返す関数の文字列化されたソースコード。定義されている場合、エンドポイントはリクエストごとに関数を実行し、関数から返された ID を持つユーザーとして実行されます。 `run_as_user_id` とは併用できません。

HTTP Service構成

非推奨のレガシー HTTP サービスは、 /http_endpoints内の名前付きサービスにグループ化されます。

http_endpoints/<Service Name>/config.json

{
  "name": "<Service Name>",
  "type": "http",
  "config": {}
}

フィールド	説明
`name` String	HTTP エンドポイントサービスの名前。これは、アプリ内のすべての HTTP エンドポイントサービス間で一意であり、含まれているディレクトリの名前と一致する必要があります。
`type` String	HTTP エンドポイントの場合、この値は常に`"http"`です。
`config` String	Additional configuration options for the service. HTTP エンドポイントには現在、追加の構成オプションはありません。

サービスアクションルール

サービスアクションルールは、サービスのrules/サブディレクトリで定義します。各ルールは、ルールと同じ名前の独自の.json構成ファイルにマッピングします。

http_endpoints/<Service Name>/rules/<Rule Name>.json

{
  "name": "<Rule Name>",
  "actions": ["<Service Action Name>"],
  "when": { <JSON Rule Expression> }
}

フィールド	説明
`name` String	サービスルールの名前。名前の長さは最大 64 文字で、ASCII 文字、数字、アンダースコア、ハイフンのみを含めることができます。
`actions` Array<String>	ルールが適用されるHTTP アクションのリスト。
`when` Document	特定のリクエストにルールが適用される場合に`true`と評価されるルール式。

受信 Webhook

構成

http_endpoints/<Service Name>/incoming_webhooks/<Webhook Name>/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>",
  "fetch_custom_user_data": <Boolean>,
  "create_user_on_auth": <Boolean>,
  "respond_result": <Boolean>,
  "options": {
    "httpMethod": "<HTTP Method>",
    "validationMethod": "<Webhook Validation Method>",
    "secret": "<Webhook Secret>"
  }
}

フィールド

説明

name

String

Webhook の名前。これは、HTTP エンドポイントサービス内のすべての Webhook 間で一意であり、含まれているディレクトリの名前と一致する必要があります。

can_evaluate

JSON Expression (default: true)

Webhook の実行が許可されている場合にtrueと評価されるJSON 式。 Atlas App Services は、すべての受信リクエストに対してこの式を評価します。

disable_arg_logs

Boolean

trueの場合、Atlas App Services は関数の実行ログエントリから Webhook に提供された引数を省略します。

run_as_authed_user

Boolean

trueの場合、Webhook 関数は受信リクエストごとに指定された既存のアプリケーションユーザー配下で実行されます。受信リクエストには、リクエスト本文またはリクエストヘッダーのいずれかにユーザーの認証プロバイダが含まれている必要があります。

Tip

認証情報を指定する方法の例については、サービス Webhook の構成を参照してください。

run_as_user_id

String

関数が常に実行されるApp Services ユーザーの一意の ID。 run_as_user_id_script_sourceまたはrun_as_authed_userとは併用できません。

run_as_user_id_script_source

String

Webhook が呼び出されるたびに実行され、関数が実行されるApp Services ユーザーの一意の ID を返す文字列化された関数。 run_as_user_idまたはrun_as_authed_userとは併用できません。

respond_result

Boolean

trueの場合、App Services は、Webhook リクエストを開始したクライアントに送信する HTTP 応答の本体として Webhook 関数の戻り値を含めます。

fetch_custom_user_data

Boolean

trueの場合、App Services はリクエスト元のユーザーのカスタムユーザーデータをクエリし、存在する場合はそのデータをオブジェクトとしてcontext.user.custom_dataプロパティで公開します。

このオプションは、 run_as_authed_userがtrueに設定されている場合にのみ使用できます。

create_user_on_auth

Boolean

trueの場合、Atlas App Services は既存のユーザー（例: 指定されたメールアドレスを持っているユーザーはいない）。新しいユーザーを作成するには、リクエスト時に認証情報に対応する認証プロバイダを有効にする必要があります。

このオプションは、 run_as_authed_userがtrueに設定されている場合にのみ使用できます。

options

Document

Webhook の構成オプションを含むドキュメント。

{
  "httpMethod": "<HTTP Method>",
  "validationMethod": "<Webhook Validation Method>",
  "secret": "<Webhook Secret>"
}

フィールド	説明
`httpMethod` String	Webhook が受け入れる HTTP メソッドの種類。受信 Webhook リクエストは、このメソッドを使用する必要があります。
`validationMethod` String	Webhook が使用するリクエスト検証方法の名前。有効なオプション: `"VERIFY_PAYLOAD"` `"SECRET_AS_QUERY_PARAM"` `"NO_VALIDATION"`
`secret` String	受信する Webhook リクエストを検証するために使用されるシークレット値。

ソースコード

Webhook 関数のソースコードは、Webhook ディレクトリ内のsource.jsファイルで定義します。各ファイルは、リクエストが Webhook を呼び出すたびに実行されるメイン関数をエクスポートする必要があります。

http_endpoints/<Service Name>/incoming_webhooks/<Webhook Name>/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!" };
};

Atlas アプリケーションサービスとは

注意

カスタム HTTPS エンドポイント構成

データ API 構成

HTTP Service構成

サービスアクション ルール

受信 Webhook

構成

Tip

ソースコード

サービスアクションルール