Archivos de configuración de puntos finales HTTP

Atlas App Services ha llegado al final de su ciclo de vida y MongoDB ya no ofrece soporte activo. Los activadores siguen disponibles en la interfaz de usuario de Atlas. Consulte Página de desuso para más detalles.

Nota

Esta página describe un formato de archivo de configuración heredado. Solo debe usar esta información si está usando el formato obsoleto. realm-cli.

Cualquier archivo de configuración que extraiga con la CLI de App Services o exporte desde la interfaz de usuario utiliza la versión más reciente. Para obtener información detallada sobre el formato actual de los archivos de configuración, consulte Configuración de la aplicación.

app/
└── http_endpoints/
    ├── config.json
    ├── data_api_config.json
    └── <Service Name>/
        ├── config.json
        ├── rules/
        │   └── <Rule Name>.json
        └── incoming_webhooks/
            └── <Webhook Name>/
                ├── config.json
                └── source.js

Configuración personalizada de punto final HTTPS

Define las configuraciones para todos los puntos finales HTTPS personalizados de tu aplicación como una matriz http_endpoints/config.json en.

[
  {
    "route": "<Endpoint route name>",
    "http_method": "<HTTP method>",
    "function_name": "<Endpoint function name",
    "validation_method": "<Authorization scheme>",
    "secret_name": "<Validation Secret Name>",
    "respond_result": <boolean>,
    "fetch_custom_user_data": <boolean>,
    "create_user_on_auth": <boolean>,
    "disabled": <boolean>
  }
]

Campo	Descripción
`route` string	La ruta del punto final.
`http_method` string	El tipo de Método HTTPque gestiona el punto final. Especifique `` para gestionar todos los métodos con un único punto final. Uno de: `"GET"` `"POST"` `"PUT"` `"PATCH"` `"DELETE"` `"DELETE"` `""`
`function_name` string	El nombre de la función asociada al punto final. La función debe usar la firma de la función del punto final.
`validation_method` string	El esquema de autorización de punto final utilizado para validar las solicitudes entrantes. Uno de: `"SECRET_AS_QUERY_PARAM"` `"VERIFY_PAYLOAD"` `"NO_VALIDATION"`
`secret_name` string	El nombre de un secreto que contiene una cadena. Si `validation_method` se establece `SECRET_AS_QUERY_PARAM` en `VERIFY_PAYLOAD` o, este secreto se utiliza para autorizar solicitudes.
`respond_result` boolean	Si `true` es, el punto final devuelve una respuesta HTTP personalizable al cliente. La respuesta se configura llamando a los métodos del objeto Respuesta. Si no se configura, el punto final devuelve una `200 - Ok` respuesta con el valor devuelto por la función endpont como cuerpo de la solicitud. Si es `false`, las solicitudes devuelven una respuesta `204 - No Content` sin datos en el cuerpo.
`fetch_custom_user_data` boolean	Si `true` es, el documento de datos de usuario personalizado del usuario autenticado está disponible a través `context.user.custom_data` de. Si es `false`, no se consultan los datos personalizados del usuario y `context.user.custom_data` es un objeto vacío.
`create_user_on_auth` boolean	Si es `true`, su aplicación crea automáticamente un nuevo usuario si las credenciales de usuario proporcionadas se autentican correctamente pero no están asociadas con un usuario existente. Esta configuración es útil para aplicaciones que se integran con un sistema de autenticación externo mediante el proveedor de autenticación JWT personalizado. Si una solicitud incluye un JWT válido del sistema externo que no corresponde a un usuario registrado, esto crea un nuevo usuario con el JWT como una identidad.
`disabled` boolean	Habilita (`false`) o deshabilita (`true`) el punto final.

Configuración de la API de datos

Define la configuración para los puntos finales de API de datos generados por tu aplicación http_endpoints/data_api_config.json en.

{
  "disabled": <boolean>,
  "versions": ["v1"],
  "return_type": "EJSON" | "JSON",
  "create_user_on_auth": <boolean>,
  "run_as_system": <boolean>,
  "run_as_user_id": "<User Account ID>",
  "run_as_user_id_script_source": "<Function Source Code>"
}

Campo	Descripción
`disabled` boolean	Si es `false`, la API de datos no está habilitada. Los puntos de conexión generados no gestionarán ni responderán a las solicitudes.
`versions` string[]	Una lista de las versiones de la API de datos compatibles con tu aplicación. La lista puede incluir un subconjunto de todas las versiones posibles, pero debe estar en orden ascendente. No puedes habilitar una versión que no sea la más reciente, pero las versiones previamente habilitadas que se indican aquí seguirán funcionando. Versiones disponibles: `"v1"`
`return_type` string	El formato de datos que se utilizará para los datos devueltos por los puntos finales en los cuerpos de respuesta HTTPS. Uno de: `"EJSON"` `"JSON"`
`create_user_on_auth` boolean	Si es `true`, su aplicación crea automáticamente un nuevo usuario si las credenciales de usuario proporcionadas se autentican correctamente pero no están asociadas con un usuario existente. Esta configuración es útil para aplicaciones que se integran con un sistema de autenticación externo mediante el proveedor de autenticación JWT personalizado. Si una solicitud incluye un JWT válido del sistema externo que no corresponde a un usuario registrado, esto crea un nuevo usuario con el JWT como una identidad.
`run_as_user_id` string	ID de cuenta de un usuario de la aplicación. Si se define, los endpoints siempre se ejecutarán con el usuario especificado. No se puede usar con `run_as_user_id_script_source`.
`run_as_user_id_script_source` string	Código fuente en cadena para una función que devuelve el ID de la cuenta de un usuario de la aplicación. Si se define, los endpoints ejecutan la función en cada solicitud y se ejecutan como el usuario con el ID devuelto por la función. No se puede usar con `run_as_user_id`.

Configuración del servicio HTTP

Los servicios HTTP heredados obsoletos se agrupan en servicios con nombre dentro de /http_endpoints.

http_endpoints/<Service Name>/config.json

{
  "name": "<Service Name>",
  "type": "http",
  "config": {}
}

Campo	Descripción
`name` String	El nombre del servicio de puntos finales HTTP. Debe ser único entre todos los servicios de puntos finales HTTP de la aplicación y coincidir con el nombre del directorio que lo contiene.
`type` String	Para los puntos finales HTTP, este valor siempre es `"http"`.
`config` String	Opciones de configuración adicionales para el servicio. Actualmente, los puntos finales HTTP no tienen opciones de configuración adicionales.

Reglas de acciones del servicio

Las reglas de acción del servicio se definen en el rules/ subdirectorio del servicio. Cada regla se asigna a su propio .json archivo de configuración con el mismo nombre que la regla.

http_endpoints/<Service Name>/rules/<Rule Name>.json

{
  "name": "<Rule Name>",
  "actions": ["<Service Action Name>"],
  "when": { <JSON Rule Expression> }
}

Campo	Descripción
`name` String	El nombre de la regla de servicio. El nombre puede tener como máximo 64 caracteres y solo puede contener letras ASCII, números, guiones bajos y guiones.
`actions` Array<String>	Una lista de acciones HTTP a las que se aplica la regla.
`when` Document	Una expresión de regla que evalúa como `true` cuando la regla se aplica a una solicitud determinada.

Webhooks entrantes

Configuración

http_endpoints/<Service Name>/incoming_webhooks/<Webhook Name>/config.json

{
  "name": "<Webhook Name>",
  "can_evaluate": { <JSON Expression> },
  "run_as_authed_user": <Boolean>,
  "run_as_user_id": "<App Services User ID>",
  "run_as_user_id_script_source": "<Function Source Code>",
  "fetch_custom_user_data": <Boolean>,
  "create_user_on_auth": <Boolean>,
  "respond_result": <Boolean>,
  "options": {
    "httpMethod": "<HTTP Method>",
    "validationMethod": "<Webhook Validation Method>",
    "secret": "<Webhook Secret>"
  }
}

Campo

Descripción

name

String

El nombre del webhook. Debe ser único entre todos los webhooks del servicio de puntos finales HTTP y coincidir con el nombre del directorio que lo contiene.

can_evaluate

JSON Expression (default: true)

Una expresión JSON que evalúa true como si se permite la ejecución del webhook. Atlas App Services evalúa esta expresión para cada solicitud entrante.

disable_arg_logs

Boolean

Si true es, App Services omite los argumentos proporcionados al webhook de la entrada del registro de ejecución de la función.

run_as_authed_user

Boolean

Si es true, la función de webhook se ejecuta en el contexto de un usuario de la aplicación existente especificado en cada solicitud entrante. Las solicitudes entrantes deben incluir las credenciales del proveedor de autenticación del usuario en el cuerpo o en los encabezados de la solicitud.

Tip

Para obtener un ejemplo de cómo especificar credenciales, consulte Configurar webhooks de servicio.

run_as_user_id

String

El ID único de un usuario de App Services con el que siempre se ejecuta la función. No se puede usar con run_as_user_id_script_source run_as_authed_userni.

run_as_user_id_script_source

String

Una función convertida en cadena que se ejecuta al llamar al webhook y devuelve el ID único del usuario de App Services que la ejecuta. No se puede usar con run_as_user_id run_as_authed_userni.

respond_result

Boolean

Si es true, App Services incluye el valor de retorno de la función webhook como el cuerpo de la respuesta HTTP que envía al cliente que inició la solicitud de webhook.

fetch_custom_user_data

Boolean

Si true es, App Services consulta los datos de usuario personalizados del usuario solicitante y, si existen, expone los datos como un objeto en la context.user.custom_data propiedad.

Esta opción sólo está disponible si run_as_authed_user está configurado en true.

create_user_on_auth

Boolean

Si es true, App Services crea automáticamente un nuevo usuario basándose en las credenciales proporcionadas si no coinciden con las de un usuario ya existente (por ejemplo, ningún otro usuario tiene la dirección de correo electrónico especificada). El proveedor de autenticación correspondiente a las credenciales debe estar habilitado al momento de la solicitud para crear un nuevo usuario.

Esta opción sólo está disponible si run_as_authed_user está configurado en true.

options

Document

Un documento que contiene opciones de configuración para el webhook.

{
  "httpMethod": "<HTTP Method>",
  "validationMethod": "<Webhook Validation Method>",
  "secret": "<Webhook Secret>"
}

Campo	Descripción
`httpMethod` String	El tipo de método HTTP que acepta el webhook. Las solicitudes entrantes de webhook deben usar este método.
`validationMethod` String	El nombre del método de validación de solicitudes utilizado por el webhook. Opciones válidas: `"VERIFY_PAYLOAD"` `"SECRET_AS_QUERY_PARAM"` `"NO_VALIDATION"`
`secret` String	El valor secreto utilizado para validar las solicitudes de webhook entrantes.

Código fuente

El código fuente de una función de webhook se define en un archivo source.js dentro del directorio del webhook. Cada archivo debe exportar la función principal que se ejecuta cuando una solicitud llama al webhook.

http_endpoints/<Service Name>/incoming_webhooks/<Webhook Name>/source.js

exports = async function (payload, response) {
  // Convert the webhook body from BSON to an EJSON object
  const body = EJSON.parse(payload.body.text());
  // Execute application logic, such as working with MongoDB
  if (body.someField) {
    const mdb = context.services.get("mongodb-atlas");
    const requests = mdb.db("demo").collection("requests");
    const { insertedId } = await requests.insertOne({
      someField: body.someField,
    });
    // Respond with an affirmative result
    response.setStatusCode(200);
    response.setBody(`Successfully saved "someField" with _id: ${insertedId}.`);
  } else {
    // Respond with a malformed request error
    response.setStatusCode(400);
    response.setBody(`Could not find "someField" in the webhook request body.`);
  }
  // This return value does nothing because we already modified the response object.
  // If you do not modify the response object and you enable *Respond with Result*,
  // App Services will include this return value as the response body.
  return { msg: "finished!" };
};

¿Qué son los servicios de aplicación Atlas?