データAPIエンドポイント [非推奨]

認証

データ API エンドポイントはユーザーごとに異なる状況で実行されるため、アプリではリクエストごとにルールを適用し、ドキュメント スキーマを検証できます。

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

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

{
  "run_as_user_id": "628e47baf4c2ac2796fc8a91"
}

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

承認

認証済みユーザーに対し、リクエストごとに追加の認証情報の提供を要求できます。すべての生成済 Data API エンドポイントの認証スキームを、Data API の構成で定義します。

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

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

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

応答タイプ

エンドポイントにより返される、データ形式は JSON または EJSON です。

デフォルトでは、最新の言語やプラットフォームにより広くサポートされている標準データ形式である JSON が返されます。ただし、JSON のデータ型表現はMongoDB で保存できるすべてのデータ型に対応していないため、一部のデータ型のタイプ情報が失わる場合があります。

また、EJSON 形式でデータを返すようにエンドポイントを構成できます。EJSON では構造化された JSON オブジェクトが使用されるため、MongoDB がサポートするデータ型をもれなく表現します。これにより、応答内の型情報を保持できますが、アプリケーションが EJSON の解析方法と使用方法を理解している必要があります。

{
   "return_type": "JSON"
}

{
   "return_type": "EJSON"
}

アクセス権限

Data API は、アプリのデータアクセス ルールを使用して、ユーザーごとに、データの読み取りと書込みができるかどうかを判断します。Data API リクエストで特定のコレクションにアクセスするには、まずそのコレクションのルールを定義する必要があります。

また、IP アクセス リストを設定してセキュリティを強化できます。

API バージョン

Data API は組み込みのバージョン管理スキームを使用して、下位互換性を維持しつつエンドポイントを経時的にアップグレードします。受信リクエストでリクエスト URL で使用するエンドポイントのバージョンを指定できます。有効にした任意のバージョンに Data API は対応できます。

新しいバージョンのエンドポイントを呼び出す前に、そのバージョンを有効にする必要があります。最新の Data API バージョンはいつでも有効にできますが、最新バージョンがリリースした後に、古いバージョンを有効にはできません。

現在、次のバージョンがサポートされています。

• beta

• v1

API バージョンの選択

Data API リクエストでは、リクエスト URL で使用する API のバージョンを指定します。リクエストでは、アプリで有効化した任意のバージョンを指定できます。

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

リクエストのデータ形式を指定する

Data API リクエストには、リクエスト本文で使用するデータ形式を指定するために Content-Type ヘッダーを含める必要があります。

• Data API リクエストの本文で標準の JSON 型を表現するには、Content-Type: application/json を使用します。

• Data API リクエストの本文で標準的な JSON 型および 追加の EJSON 型を表現するには、Content-Type: application/ejson を使用します。

curl -X GET \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/insertOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/ejson' \
  -H 'Accept: application/ejson' \
  --data-raw '{
      "dataSource": "mongodb-atlas",
      "database": "learn-data-api",
      "collection": "hello",
      "document": {
        "_id": { "$oid": "629971c0d71aad65bd59c595" },
        "greeting": "Hello, EJSON!",
        "date": { "$date": { "$numberLong": "1654589430998" } }
      }
  }'

{ "insertedId": { "$oid": "629971c0d71aad65bd59c595" } }

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/updateOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/json' \
  --data-raw '{
     "dataSource": "mongodb-atlas",
     "database": "learn-data-api",
     "collection": "hello",
     "filter": { "greeting": "Hello, world!" },
     "update": {
         "$set": { "greeting": "Hello, universe!" }
     }
  }'

{ "matchedCount": 1, "modifiedCount": 1 }

応答データ形式の選択

応答本文の特定のデータ形式（JSON または EJSON）をリクエストするには、リクエストに Accept ヘッダーを含めることができます。リクエストに有効な Accept ヘッダーがない場合、応答には Data API 構成で指定されたデータ形式が使用されます。

curl -X GET \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/ejson' \
  --data-raw '{
     "dataSource": "mongodb-atlas",
     "database": "learn-data-api",
     "collection": "hello",
     "projection": { "greeting": 1, "date": 1 }
  }'

{
  "_id": { "$oid": "629971c0d71aad65bd59c545"},
  "greeting": "Hello, Leafie!",
  "date": { "$date": { "$numberLong": "1654589430998" } }
}

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \
  -H 'apiKey: <API Key>' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  --data-raw '{
     "dataSource": "mongodb-atlas",
     "database": "learn-data-api",
     "collection": "hello",
     "projection": { "greeting": 1, "date": 1 }
  }'

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

リクエストの認証

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

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

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

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

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

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "email: bob@example" \
  -H "password: Pa55w0rd!" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "apiKey: TpqAKQgvhZE4r6AOzpVydJ9a3tB1BLMrgDzLlBLbihKNDzSJWTAHMVbsMoIOpnM6" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

curl -s "https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne" \
  -X POST \
  -H "Accept: application/json" \
  -H "jwtTokenString: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhdWQiOiJteWFwcC1hYmNkZSIsInN1YiI6IjEyMzQ1Njc4OTAiLCJuYW1lIjoiSm9obiBEb2UiLCJleHAiOjIxNDU5MTY4MDB9.E4fSNtYc0t5XCTv3S8W89P9PKLftC4POLRZdN2zOICI" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "sample_mflix",
    "collection": "movies",
    "filter": {
      "title": "The Matrix"
    }
  }'

リクエストの許可

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

curl -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne?secret=12345 \
  -H "Content-Type: application/json" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": { "text": "Do the dishes" }
  }'

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 -X POST \
  https://data.mongodb-api.com/app/myapp-abcde/endpoint/data/v1/action/findOne \
  -H "Content-Type: application/json" \
  -H "Endpoint-Signature: sha256=769cd86855787f476afc8b0d2cf9837ab0318181fca42f45f34b6dffd086dfc7" \
  -d '{
    "dataSource": "mongodb-atlas",
    "database": "learn-data-api",
    "collection": "tasks",
    "filter": { "text": "Do the dishes" }
  }'