Procesamiento y creación de documentos de Azure Cosmos DB mediante Azure Logic Apps

Se aplica a: Azure Logic Apps (consumo + estándar)

Desde el flujo de trabajo Azure Logic Apps, puede conectarse a Azure Cosmos DB y trabajar con documentos usando el conector de Azure Cosmos DB. Este conector proporciona desencadenadores y acciones que el flujo de trabajo puede usar en las operaciones de Azure Cosmos DB. Por ejemplo, entre las acciones se incluye la creación, actualización, lectura, consulta y eliminación de documentos.

Puede conectarse a Azure Cosmos DB desde los tipos de recursos tanto de aplicación lógica (consumo) como de aplicación lógica (estándar) mediante las operaciones de conector administrado. En el caso de los recursos de aplicación lógica (estándar), Azure Cosmos DB también proporciona operaciones integradas, que actualmente se encuentran en versión preliminar y que ofrecen otras funcionalidades, un rendimiento mejor y más elevado. Por ejemplo, si está trabajando con el tipo de recurso de aplicación lógica (estándar), puede usar el desencadenador integrado para responder a los cambios en un contenedor de Azure Cosmos DB. Puede combinar operaciones de Azure Cosmos DB con otras acciones y desencadenadores en sus flujos de trabajo de la aplicación lógica para habilitar escenarios como el aprovisionamiento de eventos y el procesamiento de datos general.

Limitaciones

• Actualmente, solo los flujos de trabajo con estado de un recurso de aplicación lógica (estándar) pueden usar tanto las operaciones del conector administrado como las operaciones integradas. Los flujos de trabajo sin estado solo pueden usar operaciones integradas.

• El conector de Azure Cosmos DB solo admite cuentas de Azure Cosmos DB creadas con la Azure Cosmos DB for NoSQL.

Requisitos previos

• Una cuenta y una suscripción de Azure. Si no tiene una suscripción de Azure, regístrese para obtener una cuenta gratuita de Azure.

• Una cuenta de Azure Cosmos DB.

• Un flujo de trabajo desde el que quiera acceder a la cuenta de Azure Cosmos DB. Para usar el desencadenador de Azure Cosmos DB, debe crear la aplicación lógica usando el tipo de recurso de aplicación lógica (estándar) y agregar un flujo de trabajo en blanco.

Adición de un desencadenador de Azure Cosmos DB

En Azure Logic Apps, cada flujo de trabajo debe comenzar con un desencadenador, que se activa cuando se produce un evento específico o cuando se cumple una condición determinada.

Si está trabajando con el tipo de recurso de aplicación lógica (estándar), el desencadenador integrado denominado When an item is created or modified (preview) (Cuando se crea o se modifica un elemento [versión preliminar]) está disponible y se basa en el patrón de fuente de cambios de Azure Cosmos DB. Este desencadenador no está disponible para el tipo de recurso de aplicación lógica (consumo).

Consumo

No hay ningún desencadenador de Azure Cosmos DB disponible para el tipo de recurso de aplicación lógica (consumo).

Estándar

Haga lo siguiente para agregar un desencadenador integrado de Azure Cosmos DB a un flujo de trabajo de aplicación lógica en una instancia de Azure Logic Apps de inquilino único:

1. En Azure Portal abra el flujo de trabajo de la aplicación lógica en el diseñador.

2. Haga lo siguiente para encontrar el desencadenador:

   1. En el diseñador, seleccione Elegir una operación.

   2. Cuando se abra el panel Agregar un desencadenador, en el cuadro de búsqueda Elegir una operación, seleccione Integrado.

   3. En el cuadro de búsqueda, escriba Azure Cosmos DB. En la lista de desencadenadores, seleccione el desencadenador llamado When an item is created or modified (preview) (Cuando se crea o se modifica un elemento [versión preliminar]).

   

3. Si se le piden los detalles de la conexión, cree una conexión a Azure Cosmos DB ahora.

4. En la pestaña Parámetros, proporcione la información necesaria del desencadenador.

   Propiedad	Necesario	Valor	Descripción
   Id. de base de datos	Sí	<database-name>	Nombre de la base de datos con el contenedor que desea supervisar. Esta base de datos también debe tener el contenedor de concesión. Si aún no tiene un contenedor de concesión, el conector creará uno automáticamente en un paso posterior.
   Monitored Container Id (Id. de contenedor supervisado)	Sí	<container-name>	Nombre del contenedor que desea supervisar. Este contenedor ya debe existir en la base de datos especificada.
   Lease Container Id (Id. de contenedor de concesión)	Sí	<lease-container-name>	Nombre de un contenedor de concesión existente, o un contenedor nuevo que desee crear automáticamente. El nombre del desencadenador se rellena de forma predeterminada como leases.
   Create Lease Container (Crear contenedor de concesión)	No	Sí o No	Si el contenedor de concesión ya existe en la base de datos especificada, seleccione No. Si desea que el desencadenador cree este contenedor, seleccione Sí. Si selecciona Sí y usa el rendimiento manual dedicado para cada contenedor, asegúrese de abrir la lista Agregar nuevo parámetro para seleccionar la propiedad Rendimiento del contenedor de concesión. Escriba el número de unidades de solicitud (RU) que desea aprovisionar para este contenedor.

   En la imagen siguiente se muestra un desencadenador de ejemplo:

   

   Nota:

   El desencadenador creará varias ejecuciones de flujo de trabajo para cada elemento creado o modificado en Azure Cosmos DB, por lo que la salida de contenido dinámico de este desencadenador siempre es un solo elemento.

5. Agregue cualquier otra acción que desee incluir en el flujo de trabajo.

6. En la barra de herramientas del diseñador, seleccione Save (Guardar).

Adición de una acción de Azure Cosmos DB

En Azure Logic Apps, una acción es un paso del flujo de trabajo que sigue a un desencadenador u otra acción. El conector de Azure Cosmos DB ofrece acciones para los tipos de recursos de aplicación lógica (consumo) y de aplicación lógica (estándar). Los ejemplos siguientes para cada tipo de recurso muestran cómo usar una acción que crea o actualiza un documento.

Consumo

Haga lo siguiente para agregar una acción de Azure Cosmos DB a un flujo de trabajo de aplicación lógica en una instancia de Azure Logic Apps con varios inquilinos:

1. En Azure Portal, abra el flujo de trabajo en el diseñador.

2. Si el flujo de trabajo está en blanco, agregue el desencadenador que prefiera.

   Este ejemplo comienza con el desencadenador Cuando se recibe una solicitud HTTP.

3. En el desencadenador o la acción donde quiera agregar la acción de Azure Cosmos DB, seleccione Nuevo paso o Agregar una acción, en el caso de que quiera hacerlo entre pasos.

4. En el cuadro de búsqueda del diseñador, escriba Azure Cosmos DB. Seleccione la acción de Azure Cosmos DB que quiera usar.

   En este ejemplo se usa la acción denominada Crear o actualizar documento (V3).

   

5. Si se le piden los detalles de la conexión, cree una conexión a su cuenta de Azure Cosmos DB ahora.

6. Proporcione la información necesaria para la acción.

   Propiedad	Necesario	Valor	Descripción
   Azure Cosmos DB account name (Nombre de la cuenta de Azure Cosmos DB)	Sí	Seleccione Usar configuración de conexión (<nombre de la cuenta de Azure Cosmos DB>), o escriba el nombre manualmente.	Nombre de cuenta de la cuenta de Azure Cosmos DB.
   Identificador de base de datos	Sí	<database-ID>	Base de datos a la que desea conectarse.
   ID de contenedor	Sí	<container-ID>	Contenedor que desea consultar.
   Document	Sí	<documento JSON>	Documento JSON que desea crear. En este ejemplo se usa el cuerpo de la solicitud de la salida del desencadenador. Sugerencia: Si el token Cuerpo del desencadenador HTTP no aparece en la lista de contenido dinámico para agregarlo, seleccione Ver más junto al nombre del desencadenador. Nota: Asegúrese de que el cuerpo tiene un formato JSON correcto y que contiene como mínimo la propiedad id y la propiedad de clave de partición del documento. Si ya existe un documento con la propiedad id y la clave de partición especificadas, el documento se actualiza. En caso contrario, se crea un nuevo documento.

   En la imagen siguiente se muestra una acción de ejemplo:

   

7. Configure cualquier otro ajuste de acción según corresponda.

8. En la barra de herramientas del diseñador, seleccione Save (Guardar).

9. Pruebe la aplicación lógica para asegurarse de que el flujo de trabajo crea un documento en el contenedor especificado.

Estándar

Haga lo siguiente para agregar una acción de Azure Cosmos DB a un flujo de trabajo de aplicación lógica en una instancia de Azure Logic Apps de inquilino único:

1. En Azure Portal, abra el flujo de trabajo en el diseñador.

2. Si el flujo de trabajo está en blanco, agregue el desencadenador que prefiera.

   Este ejemplo comienza con el desencadenador Cuando se recibe una solicitud HTTP, que usa una definición de esquema básica para representar el elemento que desea crear.

   

3. En el desencadenador o la acción donde quiere agregar la acción de Azure Cosmos DB, seleccione Insertar un nuevo paso (+) >Agregar una acción.

4. En el diseñador, asegúrese de que está seleccionada la opción Agregar una operación. En el panel Agregar una acción que se abre, en el cuadro de búsqueda Elegir una operación, seleccione Integrado para encontrar las acciones de Azure Cosmos DB.

   Nota:

   Si tiene un flujo de trabajo con estado, las acciones del conector administrado también están disponibles en la pestaña Azure, pero úselas solo cuando las acciones integradas que desee no estén disponibles.

5. En el cuadro de búsqueda, escriba Azure Cosmos DB. Seleccione la acción de Azure Cosmos DB que quiera usar.

   En este ejemplo se usa la acción denominada Create or update item (preview) (Crear o actualizar elemento [versión preliminar]), que crea un elemento o actualiza uno ya existente.

   

6. Si se le piden los detalles de la conexión, cree una conexión a su cuenta de Azure Cosmos DB ahora.

7. Proporcione la información necesaria para la acción.

   Propiedad	Necesario	Valor	Descripción
   Id. de base de datos	Sí	<database-ID>	Base de datos a la que desea conectarse.
   Id. de contenedor	Sí	<container-ID>	Contenedor que desea consultar.
   Elemento	Sí	<documento JSON>	Documento JSON que desea crear. En este ejemplo se usa el cuerpo de la solicitud de la salida del desencadenador. Sugerencia: Si el token Cuerpo del desencadenador HTTP no aparece en la lista de contenido dinámico para agregarlo, seleccione Ver más junto al nombre del desencadenador. Nota: Asegúrese de que el cuerpo tiene un formato JSON correcto y que contiene como mínimo la propiedad id y la propiedad de clave de partición del documento. Si ya existe un documento con la propiedad id y la clave de partición especificadas, el documento se actualiza. En caso contrario, se crea un nuevo documento.
   Clave de partición	No	<partition-key>	Valor de clave de partición del documento que desea crear.

   En la imagen siguiente se muestra una acción de ejemplo:

   

8. Configure cualquier otro ajuste de acción según corresponda.

9. En la barra de herramientas del diseñador, seleccione Save (Guardar).

10. Pruebe la aplicación lógica para asegurarse de que el flujo de trabajo crea un documento en el contenedor especificado.

Conexión a Azure Cosmos DB

Al agregar un desencadenador o una acción que se conecta a un servicio o sistema, y no tiene una conexión existente o activa, Azure Logic Apps le pide que proporcione la información de conexión, que varía en función del tipo de conexión, por ejemplo:

• Las credenciales de la cuenta
• El nombre que se va a usar para la conexión
• Nombre del sistema o servidor
• Tipo de autenticación que se debe usar.
• Una cadena de conexión

Para poder configurar el desencadenador de Azure Cosmos DB o la acción de Azure Cosmos DB, debe conectarse a una cuenta de base de datos.

Consumo

En un flujo de trabajo de aplicación lógica (consumo), una conexión de Azure Cosmos DB requiere los siguientes valores de propiedad:

Propiedad	Necesario	Valor	Descripción
Nombre de la conexión	Sí	<connection-name>	El nombre que se usa para su conexión.
Tipo de autenticación	Sí	<connection-type>	El tipo de autenticación que desea utilizar. En este ejemplo se usa Clave de acceso. - Si selecciona Clave de acceso, proporcione los valores de propiedad necesarios restantes para crear la conexión. - Si selecciona Microsoft Entra integrado, no se requieren otros valores de propiedad, pero debe configurar la conexión siguiendo los pasos para la autenticación de Microsoft Entra y el conector de Azure Cosmos DB.
Clave de acceso a la cuenta de Azure Cosmos DB	Sí	<clave de acceso>	Clave de acceso de la cuenta de Azure Cosmos DB que se usará para esta conexión. Este valor es una clave de lectura y escritura o una clave de solo lectura. Nota: Para encontrar la clave, vaya a la página de la cuenta de Azure Cosmos DB. En el menú de navegación, en Configuración, seleccione Claves. Copie uno de los valores de clave disponibles.
Id. de cuenta	Sí	<identificador de la cuenta>	Nombre de la cuenta de Azure Cosmos DB que se usará para esta conexión.

La siguiente imagen muestra una conexión de ejemplo:

Nota:

Después de crear la conexión, si tiene una conexión de Azure Cosmos DB existente distinta que quiera usar en su lugar, o si prefiere crear otra conexión desde cero, seleccione Cambiar conexión en el editor de detalles del desencadenador o la acción.

Estándar

En un flujo de trabajo de aplicación lógica (estándar), una conexión de Azure Cosmos DB requiere los siguientes valores de propiedad:

Propiedad	Necesario	Valor	Descripción
Nombre de la conexión	Sí	<connection-name>	El nombre que se usa para su conexión.
Cadena de conexión	Sí	<cadena de conexión>	Cadena de conexión de Azure Cosmos DB que se usará para la conexión. Nota: Para encontrar la cadena de conexión, vaya a la página de la cuenta de Azure Cosmos DB. En el menú de navegación, en Configuración, seleccione Claves. Copie uno de los dos valores de cadena de conexión disponibles.

La siguiente imagen muestra una conexión de ejemplo:

Nota:

Después de crear la conexión, si tiene una conexión de Azure Cosmos DB existente distinta que quiera usar en su lugar, o si prefiere crear otra conexión desde cero, seleccione Cambiar conexión en el editor de detalles del desencadenador o la acción.

Referencia de conector

Para obtener información de referencia sobre las distintas operaciones de conector administrado de Azure Cosmos DB (como los desencadenadores, las acciones y los límites), revise la página de referencia del conector.

No existe ninguna página de referencia relativa a las operaciones integradas de Azure Cosmos DB. En su lugar, revise la tabla siguiente para obtener más información:

Tipo	Nombre	Parámetros
Desencadenador	Cuando se crea o modifica un elemento	- Id. de base de datos: obligatorio. Nombre de la base de datos con los contenedores supervisado y de concesión. - Id. de contenedor supervisado: obligatorio. Nombre del contenedor que se está supervisando. - Id. de contenedor de concesión: obligatorio. Nombre del contenedor utilizado para almacenar concesiones. - Crear contenedor de concesión: obligatorio. Si es true, cree el contenedor de concesión si aún no existe. - Rendimiento del contenedor de concesión: opcional. Número de unidades de solicitud que se asignarán al crear el contenedor de concesión.
Acción	Create or update item (Crear o actualizar elemento)	- Id. de base de datos: obligatorio. El nombre de la base de datos. - Id. de contenedor: obligatorio. nombre del contenedor. - Elemento: obligatorio. Elemento que se creará o actualizará. - Clave de partición: opcional. Valor de clave de partición del elemento solicitado. - Is Upsert (Es upsert): opcional. Si es true, reemplace el elemento (si existe). De lo contrario, cree el elemento.
Acción	Create or update many items in bulk (Crear o actualizar muchos elementos de forma masiva)	Esta acción está optimizada para escenarios de alto rendimiento y tiene procesamiento adicional antes de que la acción envíe los elementos que se crearán en el contenedor de Azure Cosmos DB. Si el número de elementos es elevado, este procesamiento adicional acelera el tiempo total de solicitud. Si el número es reducido, esta sobrecarga adicional puede tener un rendimiento más lento que si se usan varias acciones de creación de elementos individuales. - Id. de base de datos: obligatorio. El nombre de la base de datos. - Id. de contenedor: obligatorio. nombre del contenedor. - Elementos: obligatorio. Matriz de los elementos que se crearán o actualizarán. - Is Upsert (Es upsert): opcional. Si es true, reemplace un elemento (si existe). De lo contrario, cree el elemento.
Acción	Lectura de un elemento	- Id. de base de datos: obligatorio. El nombre de la base de datos. - Id. de contenedor: obligatorio. nombre del contenedor. - Id. de elemento: obligatorio. Valor de id del elemento solicitado. - Clave de partición: obligatoria. Valor de clave de partición del elemento solicitado.
Acción	Eliminación de un elemento	- Id. de base de datos: obligatorio. El nombre de la base de datos. - Id. de contenedor: obligatorio. nombre del contenedor. - Id. de elemento: obligatorio. Valor de id del elemento solicitado. - Clave de partición: obligatoria. Valor de clave de partición del elemento solicitado.
Acción	Elementos de consulta	- Id. de base de datos: obligatorio. El nombre de la base de datos. - Id. de contenedor: obligatorio. nombre del contenedor. - Consulta SQL: obligatorio. Texto de la consulta SQL de Azure Cosmos DB. - Clave de partición: opcional. Valor de clave de partición de la solicitud, si lo hay. - Token de continuación: opcional. Token de continuación de esta consulta que proporciona el servicio Azure Cosmos DB, si lo hay. - Recuento máximo de elementos: opcional. Número máximo de elementos que se devolverán en la consulta.

Procedimientos recomendados de operaciones integradas de Azure Cosmos DB

Obtener resultados iterables de la acción Elementos de consulta

La acción integrada Elementos de consulta en un flujo de trabajo de Aplicación lógica (Estándar) tiene muchas salidas de contenido dinámico disponibles para su uso en acciones posteriores. Para obtener los elementos de resultado de la consulta o los metadatos del elemento como un objeto iterable, siga estos pasos:

1. En Azure Portal, abra el flujo de trabajo en el diseñador.

2. Si el flujo de trabajo está en blanco, agregue el desencadenador que prefiera.

   Este ejemplo comienza con el desencadenador Periodicidad.

3. En el desencadenador o la acción donde quiere agregar la acción de Azure Cosmos DB, seleccione Insertar un nuevo paso (+) >Agregar una acción.

4. En el diseñador, asegúrese de que está seleccionada la opción Agregar una operación. En el panel Agregar una acción que se abre, en el cuadro de búsqueda Elegir una operación, seleccione Integrado para encontrar las acciones de Azure Cosmos DB.

5. En el cuadro de búsqueda, escriba Azure Cosmos DB. Seleccione la acciónQuery items (preview) (Consultar elementos [versión preliminar]).

6. Si se le piden los detalles de la conexión, cree una conexión a su cuenta de Azure Cosmos DB.

7. Proporcione la información necesaria para la acción.

   Propiedades	Obligatorio	Valor	Descripción
   Id. de base de datos	Sí	<database-ID>	Base de datos a la que desea conectarse.
   Id. de contenedor	Sí	<container-ID>	Contenedor que desea consultar.
   Consulta SQL	Sí	<consulta sql>	Consulta SQL de la solicitud.

   En la imagen siguiente se muestra una acción de ejemplo:

   

8. Configure cualquier otro ajuste de acción según corresponda.

9. En la acción, seleccione Permite agregar un nuevo paso (+) >Agregar una acción. En el panel Agregar una acción que se abre, seleccione la acción que desea ejecutar en todos los elementos de resultado de la consulta.

En este ejemplo se usa la acción integrada de Azure Cosmos DB denominada Eliminar un elemento (versión preliminar).

1. En la acción que agregó anteriormente, puede acceder a los datos desde la salida de la acción de consulta. Haga clic dentro de cualquiera de los campos de entrada de esa acción para que aparezca la lista de contenido dinámico. Seleccione cualquiera de los elementos de respuesta disponibles o seleccione Ver más para obtener más opciones.

En este ejemplo se usa el identificador de elemento de respuesta del campo identificador de elemento para rellenarlos en función de los resultados de la consulta.

1. Después de seleccionar un elemento de respuesta, la acción For each se agrega automáticamente para recorrer en iteración todos los resultados de la consulta. El bucle For each contiene la acción que agregó anteriormente. Puede agregar cualquier otra acción que desee incluir en el bucle.

2. En la barra de herramientas del diseñador, seleccione Save (Guardar).

3. Pruebe la aplicación lógica para asegurarse de que el flujo de trabajo devuelve la salida que espera.

Pasos siguientes

• Desencadenadores y acciones integrados para Logic Apps
• Conectores integrados para Azure Logic Apps
• ¿Qué son los conectores en Azure Logic Apps?