사용자 지정 HTTPS 엔드포인트 [사용 중단됨]

기본 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 endpoints에는 엔드포인트의 이름 역할을 하는 경로가 있습니다. 엔드포인트의 경로는 임의로 정해지며 앱에 따라 다릅니다. 하지만 엔드포인트 URL 경로에 표시되기 때문에 경로가 실행하는 조치를 나타내야 합니다.

경로 이름은 슬래시(/)로 시작해야 하며 중첩된 경로를 나타내는 추가 슬래시를 포함할 수 있습니다.

/my/nested/route

앱의 기본 URL에 경로를 추가하고 HTTP 요청을 보내 엔드포인트를 호출합니다.

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

HTTP 메서드

앱 의 각 엔드포인트는 하나 이상의 HTTP 메서드 를 처리합니다. 지정된 경로에 대해 예를 예시 POST 새 리소스 를 만드는 요청과 GET 기존 리소스를 나열하는 요청 을 수락하는 단일 경로가 있을 수 있습니다.

경로는 동일하지만 서로 다른 요청 메서드를 처리하는 여러 개의 사용자 지정 엔드포인트를 정의할 수 있습니다. 또는, 모든 메서드를 처리하는 경로를 위한 단일 엔드포인트를 정의할 수 있습니다.

사용자 지정 엔드포인트는 다음과 같은 표준 HTTP 메서드를 지원합니다.

• 얻다

• POST

• PUT

• 패치

• 삭제

인증

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

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

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

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

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

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

권한 부여

엔드포인트는 인증된 사용자에게 요청에 추가 권한 부여 정보를 제공하도록 요구할 수 있습니다. 엔드포인트 기능을 구성하여 각 사용자 정의 엔드포인트에 대한 권한 부여 체계를 정의합니다.

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

특정 함수에 대한 권한 부여 방법을 알아보려면 함수 정의를 참조하세요.

[
  {
     ...,
     "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 포함)이 표시됩니다.

응답 데이터 형식 선택하기

요청에는 응답 본문에 대한 특정 데이터 형식(JSON 또는 EJSON)을 요청하기 위한 Accept 헤더가 포함될 수 있습니다. 요청에 유효한 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"
}

요청 인증

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

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

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

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