데이터 API 엔드포인트 [사용 중단됨]

인증

데이터 API 엔드포인트는 특정 사용자의 컨텍스트에서 실행되며, 이를 통해 앱이 각 요청에 대해 규칙을 시행하고 문서 스키마의 유효성을 검사할 수 있습니다.

기본적으로 엔드포인트는 API 키 또는 JWT와 같은 애플리케이션 사용자 중 한 명의 자격 증명을 각 요청에 포함하도록 요구하는 애플리케이션 인증을 사용합니다. 또한 애플리케이션의 요구 사항에 맞게 다른 사용자 지정 인증 체계를 구성할 수도 있습니다.

요청을 인증하는 방법의 예는 데이터 API 요청 인증을 참조하세요.

{
  "run_as_user_id": "628e47baf4c2ac2796fc8a91"
}

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

권한 부여

각 요청에서 인증된 사용자에게 추가적인 권한 부여 정보를 제공하도록 요구할 수 있습니다. 데이터 API 구성에서 생성된 모든 데이터 API 엔드포인트에 대한 권한 부여 체계는 직접 정의합니다.

엔드포인트는 기본적으로 요청이 권한 부여되었음을 증명하기 위해 시크릿 문자열을 사용하는 내장 권한 부여 체계 집합을 지원합니다. 내장 체계와 함께 사용하거나 내장 체계 대신 사용할 수 있는 사용자 지정 권한 부여 체계를 정의할 수도 있습니다.

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

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

응답 유형

엔드포인트는 2가지 데이터 형식(JSON 또는 EJSON) 중 하나로 데이터를 반환할 수 있습니다.

기본적으로 엔드포인트는 최신 언어 및 플랫폼에서 널리 지원되는 표준 데이터 형식인 JSON을 반환합니다. 그러나 JSON은 MongoDB에 저장할 수 있는 모든 데이터 유형을 표현할 수 없으며 일부 데이터 유형에 대한 유형 정보가 손실됩니다.

EJSON(구조화된 JSON 객체를 사용하여 MongoDB가 지원하는 유형을 완벽하게 표현함)을 반환하도록 엔드포인트를 구성할 수도 있습니다. 이렇게 하면 유형 정보가 응답에 저장되지만, 해당 애플리케이션이 EJSON을 구문 분석하고 사용하는 방법을 이해해야 합니다.

{
   "return_type": "JSON"
}

{
   "return_type": "EJSON"
}

액세스 권한

데이터 API는 앱의 데이터 액세스 규칙을 사용하여 사용자가 데이터를 읽고 쓸 수 있는지 여부를 결정합니다. 데이터 API 요청이 특정 컬렉션에 액세스할 수 있도록 허용하려면 먼저 컬렉션에 대한 규칙을 정의해야 합니다.

추가 보안을 위해 IP 액세스 목록을 설정할 수 있습니다.

API 버전

데이터 API는 내장 버전 관리 체계를 사용하여 이전 버전과의 호환성을 유지하면서 시간이 지남에 따라 엔드포인트를 업그레이드합니다. 수신 요청은 요청 URL에서 사용할 엔드포인트 버전을 지정할 수 있으며, 데이터 API는 활성화한 모든 버전을 제공할 수 있습니다.

사용자가 해당 버전으로 엔드포인트를 호출하려면 새 버전을 활성화해야 합니다. 언제든지 최신 데이터 API 버전을 활성화할 수 있습니다. 그러나 최신 버전이 출시된 후에는 이전 버전을 활성화할 수 없습니다.

현재 지원되는 버전은 다음과 같습니다.

• beta

• v1

API 버전 선택

데이터 API 요청은 요청 URL에 사용할 API 버전을 지정합니다. 요청은 앱에서 사용 가능한 모든 버전을 지정할 수 있습니다.

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

요청 데이터 형식 지정

데이터 API 요청에는 요청 본문에서 사용된 데이터 형식을 지정하는 Content-Type 헤더가 포함되어야 합니다.

• 데이터 API 요청 본문에서 표준 JSON 유형을 나타내려면 Content-Type: application/json을 사용합니다.

• 데이터 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 헤더가 포함되지 않은 경우 응답은 데이터 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"
}

요청 인증

엔드포인트가 Application Authentication(애플리케이션 인증)을 사용하도록 구성된 경우, 모든 요청에 유효한 사용자 액세스 토큰 또는 로그인 자격 증명을 포함시켜야 합니다.

액세스 토큰을 이용한 베어러 인증은 일반적으로 처리량이 더 높고 자격 증명 헤더보다 안전합니다. 가능하다면 자격 증명 헤더 대신 액세스 토큰을 사용하세요. 이 토큰을 사용하면 사용자를 재인증하지 않고도 여러 요청을 실행할 수 있습니다. 이외에 CORS를 실행하는 웹 브라우저에서 요청을 보낼 수도 있습니다.

액세스 토큰을 사용하려면 먼저 App Services 인증 제공자를 통해 사용자를 인증하세요. 그런 다음 App Services에서 반환된 액세스 토큰을 가져오고, Bearer(베어러) 토큰 체계를 이용하여 요청의 권한 부여 헤더에 이 토큰을 입력하세요. 액세스 토큰의 획득 및 사용 방법에 대한 자세한 내용은 Bearer Token Authentication(베어러 토큰 인증)을 참조하세요.

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" }
  }'