カスタム HTTPSHTTPS endpoints エンドポイント [非推奨]

ベース URL

アプリ内のエンドポイントはベース URL を共有します。URL は、あなたのアプリ ID を使用してアプリを一意に指します。

グローバルにデプロイされたアプリは、次の形式を使用します。

https://data.mongodb-api.com/app/<App ID>/endpoint

ローカルにデプロイされたアプリのエンドポイントは、アプリのデプロイリージョンに固有のベースURLを使用します（例: us-east-1）

https://<Region>.aws.data.mongodb-api.com/app/<App ID>/endpoint

エンドポイント ルート

すべての HTTPS エンドポイントには、エンドポイントの名前として機能するルートがあります。エンドポイントのルートは任意であり、アプリに固有です。ただし、エンドポイント URL パスに表示されるため、ルートが実行するアクションを表す必要があります。

ルート名はフォワードスラッシュ（/）で始める必要があり、ネストされたパスを示すためにフォワードスラッシュを追加してもかまいません。

/my/nested/route

エンドポイントを呼び出すには、そのルートをアプリのベース URL に追加して HTTP リクエストを送信します。

https://data.mongodb-api.com/app/<App ID>/endpoint/my/nested/route

HTTP メソッド

アプリ内の各エンドポイントは 1 つ以上の HTTP メソッド を処理します （特定のルートの場合）。たとえば、新しいリソースを作成するためのPOSTリクエストと、既存のリソースを一覧表示するためのGETリクエストを受け入れるルートが 1 つあるとします。

同じルートを提供するけれども異なるリクエスト メソッドを取り扱う、複数のカスタム エンドポイントを定義できます。あるいは、すべてのメソッドを取り扱うルートの単一のエンドポイントを定義することもできます。

カスタム エンドポイントは、次の標準 HTTP メソッドをサポートします。

• GET

• POST

• PUT

• PATCH

• DELETE

認証

カスタム エンドポイントは特定のユーザーのコンテキストで実行されるため、アプリはリクエストごとにルールを適用し、ドキュメント スキーマを検証できます。

デフォルトでは、エンドポイントはアプリケーション認証を使用します。アプリケーション認証では、各リクエストに API キーや JWT などのアプリケーション　ユーザーの認証情報を含める必要があります。アプリケーションのニーズに合わせて、他のカスタム認証スキームを構成することもできます。

リクエストを認証する方法の例については、「 データ API リクエストの認証」を参照してください。

[
  {
    ...,
    "run_as_user_id": "628e47baf4c2ac2796fc8a91"
  }
]

[
  {
    ...,
    "run_as_user_id_script_source": "exports = () => {return \"628e47baf4c2ac2796fc8a91\"}"
  }
]

[
  {
    ...,
    "run_as_system": true
  }
]

承認

エンドポイントは、認証されたユーザーに対して、リクエストの中で追加の承認情報を提供することを要求できます。エンドポイント機能を設定することで、各カスタム エンドポイントの承認スキームを定義します。

エンドポイントは、リクエストが承認されたことを証明するために、kubernetes secret string を使用する一連の組み込み承認スキームをネイティブでサポートしています。また、組み込みスキームと一緒に、または組み込みスキームの代わりに使用できるカスタム承認スキームを定義することもできます。

特定の関数の認証を設定する方法については、「関数の定義」を参照してください。

[
  {
     ...,
     "verification_method": "SECRET_AS_QUERY_PARAM",
     "secret_name": "secret_verification_string"
  }
]

[
  {
     ...,
     "can_evaluate": {
       "%%request.requestHeaders.x-secret-key": "my-secret"
     }
  }
]

リクエストデータへのアクセス

カスタムエンドポイント Request オブジェクトは、エンドポイントを呼び出した HTTP リクエストを表します。受信リクエストのヘッダー、クエリ パラメーター、ボディ データにアクセスできます。

{
  "headers": { "<Header>": ["<Header Value>"] },
  "query": { "<Query Parameter>": "<Parameter Value>" },
  "body": <BSON.Binary>
}

{
  "regions": "na&eu",
  "currency": "USD"
}

{
  "Content-Type": ["application/json"],
  "Accept": ["application/json"],
  "X-CustomHeader": ["some-value", "some-other-value"]
}

// Convert the request body to a JSON string
const serialized = request.body.text();
// Parse the string into a usable object
const body = JSON.parse(serialized);

HTTPS 応答の返信

カスタム エンドポイント Response オブジェクトを使用すると、呼び出し元に返される HTTPS 応答を構成できます。ステータス コードを設定したり、ヘッダーをカスタマイズしたり、応答本体にデータを含めたりできます。

response.setStatusCode(201);

response.setBody(
  "{'message': 'Hello, World!'}"
);

response.setHeader(
  "Content-Type",
  "application/json"
);

response.addHeader(
  "Cache-Control",
  "max-age=600"
);
response.addHeader(
  "Cache-Control",
  "min-fresh=60"
)

例

受信した POST リクエストの本体を解析し、解析された本体を MongoDB コレクションに格納し、呼び出し元に応答するエンドポイント関数を考えてみましょう。

exports = async function MyCustomEndpoint(request, response) {
  try {
    // 1. Parse data from the incoming request
    if (request.body === undefined) {
      throw new Error(`Request body was not defined.`);
    }
    const body = JSON.parse(request.body.text());
    // 2. Handle the request
    const { insertedId } = await context.services
      .get("mongodb-atlas")
      .db("myDb")
      .collection("myCollection")
      .insertOne({ date: new Date(), requestBody: body });
    // 3. Configure the response
    response.setStatusCode(201);
    // tip: You can also use EJSON.stringify instead of JSON.stringify.
    response.setBody(
      JSON.stringify({
        insertedId,
        message: "Successfully saved the request body",
      })
    );
  } catch (error) {
    response.setStatusCode(400);
    response.setBody(error.message);
  }
};

この関数は、次の POST リクエストを受け取ります。

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/custom" \
  -X POST \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{
    "type": "event",
    "date": "2024-01-01T00:00:00.000Z",
    "name": "New Year Begins",
    "comment": "Happy New Year!"
  }'

{
  "message": "Successfully saved the request body",
  "insertedId": "639a521bbdec9b85ba94014b"
}

関数は受信リクエストの本体が定義されていることを確認した後、解析された本体を新しいドキュメントとして myCollection という名前のコレクションに格納します。結果の出力には、カスタム メッセージと insertedId を含む構成済みの応答が表示されます。

応答データ形式の選択

リクエストに Accept ヘッダーを含めて、レスポンス本文の特定のデータ形式（JSON または EJSON）をリクエストできます。リクエストに有効な Accept ヘッダーが含まれていない場合、レスポンスはエンドポイント構成で指定されたデフォルトのデータ形式を使用します。

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello/latest" \
  -X GET \
  -H "Accept: application/ejson" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6"

{
  "greeting": "Hello, Leafie!",
  "date": { "$date": { "$numberLong": "1654589430998" } }
}

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello/latest" \
  -X GET \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6"

{
  "greeting": "Hello, Leafie!",
  "date": "2022-06-07T08:10:30.998Z"
}

リクエストの認証

エンドポイントがアプリケーション認証を使用するように設定されている場合は、すべてのリクエストに有効なユーザー アクセス トークンまたはログイン認証情報を含める必要があります。

一般に、アクセストークンを使用したベアラ認証は、認証情報ヘッダーよりもスループットが高く、安全です。可能な場合は、認証情報ヘッダーの代わりにアクセス トークンを使用します。トークンを使用すると、ユーザーを再認証せずに複数のリクエストを実行できます。また、CORS を適用するウェブ ブラウザからリクエストを送信することもできます。

アクセストークンを使用するには、まず、App Services 認証プロバイダを介してユーザーを認証します。次に、App Services から返されたアクセス トークンを取得し、Bearer トークン スキームを使用してリクエストの許可ヘッダーに含めます。 アクセストークンの取得方法と使用方法の詳細については、「Bearer トークン認証」を参照してください。

curl -X GET \
   -H 'Authorization: Bearer <AccessToken>' \
   -H 'Content-Type: application/json' \
   https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello

あるいは、リクエスト ヘッダーにユーザーの有効なログイン資格情報を含めることもできます。

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello" \
  -X POST \
  -H "Accept: application/json" \
  -H "email: bob@example" \
  -H "password: Pa55w0rd!" \
  -d '{ "name": "Bob" }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello" \
  -X POST \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{ "name": "Alice" }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/hello" \
  -X POST \
  -H "Accept: application/json" \
  -H "jwtTokenString: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJ0ZXN0LWN1c3RvbS1lbmRwb2ludHMtZWhtenQiLCJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiZXhwIjoyMTQ1OTE2ODAwfQ.pIMvnXWrcDvmPzmE33ZPrwkBAFSwy-GxW8sP-qLtYiw" \
  -d '{ "name": "Carlos" }'

リクエストの許可

エンドポイントの構成によっては、リクエストに追加の承認情報を含める必要がある場合があります。

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/passwordRequired?secret=Super5ecr3tPa55w0rd" \
  -X GET \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{ "data": "VGhpcyBpcyBzb21lIGRhdGEgdGhhdCB3YXMgZW5jb2RlZCBhcyBhIEJhc2U2NCBBU0NJSSBzdHJpbmc=" }'

Endpoint-Signature: sha256=<hex encoded hash>

/**
 * Generate an HMAC request signature.
 * @param {string} secret - The secret validation string, e.g. "12345"
 * @param {object} body - The endpoint request body e.g. { "message": "MESSAGE" }
 * @returns {string} The HMAC SHA-256 request signature in hex format.
 */
exports = function signEndpointRequest(secret, body) {
  const payload = EJSON.stringify(body);
  return utils.crypto.hmac(payload, secret, "sha256", "hex");
};

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/sendMessage" \
  -X POST \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -H "Endpoint-Signature: sha256=d4f0537db4e230d7a6028a6f7c3bb1b57c9d16f39176d78697e559ac333e0b36" \
  -d '{ "message": "Hello!" }'