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 puntos finales personalizados admiten los siguientes métodos HTTP estándar:

• Obtener

• PUBLICAR

• PUT

• PARCHE

• ELIMINAR

Autenticación

Los puntos finales personalizados se ejecutan en el contexto de un usuario específico, lo que permite que su aplicación aplique reglas y valide esquemas de documentos para cada solicitud.

De forma predeterminada, los endpoints utilizan la autenticación de aplicaciones, que requiere que cada solicitud incluya las credenciales de uno de los usuarios de la aplicación, como una clave API o JWT. También puede configurar otros esquemas de autenticación personalizados para adaptarlos a las necesidades de su 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 punto final puede requerir que los usuarios autenticados proporcionen información de autorización adicional en la solicitud. El esquema de autorización para cada punto final personalizado se define configurando la función de punto final.

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 saber cómo configurar la autorización para una función específica, consulte Definir una función.

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

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

Solicitud de acceso a datos

Un objeto de punto final personalizado Request representa la solicitud HTTP que llamó al punto final. Puede acceder a los encabezados, parámetros de consulta y datos del cuerpo de la solicitud entrante.

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

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

Después de que la función verifica que el cuerpo de la solicitud entrante esté definido, almacena el cuerpo analizado como un nuevo documento en una colección llamada myCollection. La salida resultante muestra la respuesta configurada, que incluye un mensaje personalizado y insertedId.

Elija un formato de datos de respuesta

Una solicitud puede incluir un encabezado Accept para solicitar un formato de datos específico para el cuerpo de la respuesta, ya sea JSON o EJSON. Si una solicitud no incluye un encabezado Accept válido, la respuesta utiliza el formato de datos predeterminado especificado en la configuración del punto de conexión.

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