Puntos finales HTTPS personalizados

URL base

Los puntos finales de una aplicación comparten una URL base. Esta URL usa el ID de la aplicación para dirigirse de forma única a ella.

Las aplicaciones distribuidas globalmente emplean el siguiente formato:

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

Los puntos finales en una aplicación implementada localmente usan una URL base específica para la región de implementación de la aplicación (por ejemplo, us-east-1)

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

Rutas de punto final

Cada endpoint HTTPS tiene una ruta que sirve como nombre para el endpoint. La ruta de un endpoint es arbitraria y específica de tu aplicación. Sin embargo, aparece en la ruta URL del endpoint y por lo tanto debe ser representativa de la acción que realiza la ruta.

Los nombres de las rutas deben comenzar con una barra diagonal (/) y pueden contener barras diagonales adicionales para indicar una ruta anidada.

/my/nested/route

Para llamar a un punto final, agregue su ruta a la URL base de su aplicación y envíe una solicitud HTTP.

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

Métodos HTTP

Cada punto final de su aplicación maneja uno o más Métodos HTTPPara una ruta determinada. Por ejemplo, podría tener una sola ruta que acepte POST solicitudes para crear un nuevo recurso y una GET para listar los recursos existentes.

Puede definir varios puntos de conexión personalizados que sirvan a la misma ruta, pero que gestionen diferentes métodos de solicitud. También puede definir un único punto de conexión para la ruta que gestione todos los métodos.

Los endpoints personalizados soportan los siguientes métodos HTTP estándar:

• OBTENER

• publicación

• PUT

• PATCH

• Borrar

Autenticación

Custom endpoints run in the context of a specific user, which allows your app to enforce rules and validate document schemas for each request.

Por defecto, los endpoints usan autenticación de la aplicación, lo que requiere que cada solicitud incluya credenciales para uno de tus usuarios de la aplicación, como una clave de API o JWT. También puedes configurar otros esquemas de autenticación personalizados para adaptarlos a las necesidades de tu aplicación.

Para obtener ejemplos de cómo autenticar solicitudes, consulte Autenticar solicitudes de API de datos.

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

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

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

Autorización

Un endpoint puede requerir que los usuarios autenticados brinden información adicional de autorización en la solicitud. Defines el esquema de autorización para cada endpoint personalizado configurando la función del endpoint.

Los endpoints admiten de forma nativa un conjunto de esquemas de autorización integrados que utilizan una cadena secreta para demostrar que la solicitud está autorizada. También puede definir un esquema de autorización personalizado que pueda usar junto con los esquemas integrados o en lugar de ellos.

Para aprender a configurar la autorización para una función específica, consulta Definir una función.

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

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

Datos de solicitud de acceso

A custom endpoint Request object represents the HTTP request that called the endpoint. You can access the incoming request's headers, query parameters, and body data.

{
  "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);

Devuelve una respuesta HTTPS

Un objeto de punto final personalizado Response permite configurar la respuesta HTTPS enviada al emisor. Se puede configurar el código de estado, personalizar los encabezados e incluir datos en el cuerpo de la respuesta.

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"
)

Ejemplo

Considere una función de punto final que analiza el cuerpo de una solicitud POST entrante, almacena el cuerpo analizado en una colección MongoDB y luego responde al llamador:

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);
  }
};

La función recibe la siguiente solicitud de 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"
}

After the function verifies that the body of the incoming request is defined, it stores the parsed body as a new document in a collection named myCollection. The resulting output displays the configured response, which includes a custom message and the insertedId.

Elija un formato de datos de respuesta

A request can include an Accept header to request a specific data format for the response body, either JSON or EJSON. If a request does not include a valid Accept header, the response uses the default data format specified in the endpoint configuration.

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

Autenticar la solicitud

Si un punto final está configurado para usar la autenticación de aplicaciones, debe incluir un token de acceso de usuario válido o credenciales de inicio de sesión con cada solicitud.

En general, la autenticación de portador con un token de acceso ofrece mayor rendimiento y es más segura que los encabezados de credenciales. Utilice un token de acceso en lugar de encabezados de credenciales siempre que sea posible. El token permite ejecutar múltiples solicitudes sin tener que volver a autenticar al usuario. También permite enviar solicitudes desde un navegador web que implemente CORS.

Para usar un token de acceso, primero autentique al usuario mediante un proveedor de autenticación de App Services. Luego, obtenga el token de acceso devuelto por App Services e inclúyalo en el encabezado de autorización de la solicitud mediante un esquema de token de portador. Para obtener más información sobre cómo adquirir y usar un token de acceso,consulte Autenticación de token de portador.

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

Otra opción es incluir credenciales de inicio de sesión válidas para el usuario en las cabeceras de la solicitud.

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

Autorizar la solicitud

Dependiendo de la configuración del punto final, es posible que sus solicitudes deban incluir información de autorización adicional.

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