Leer en inglés

Compartir a través de

Diagnóstico y solución de problemas con el desencadenador de Azure Functions para Azure Cosmos DB for NoSQL

  • Artículo

SE APLICA A: NoSQL

En este artículo se abordan los problemas comunes, las soluciones alternativas y los pasos de diagnóstico al usar el desencadenador de Azure Functions para Azure Cosmos DB for NoSQL.

Dependencias

El desencadenador de Azure Functions y los enlaces para Azure Cosmos DB for NoSQL dependen del paquete de extensión Microsoft.Azure.WebJobs.Extensions.CosmosDB a través del entorno de ejecución básico de Azure Functions. Mantenga siempre estos paquetes actualizados, ya que incluyen correcciones y características nuevas que ayudan a solucionar los posibles problemas.

Consumo independiente del SDK de Azure Cosmos DB

La funcionalidad clave del paquete de extensión consiste en proporcionar compatibilidad con el desencadenador de Azure Functions y los enlaces para Azure Cosmos DB. El paquete también incluye el SDK de Azure Cosmos DB .NET, lo que resulta útil si desea interactuar con Azure Cosmos DB mediante programación sin usar el desencadenador ni enlaces.

Si quiere usar el SDK de Azure Cosmos DB, asegúrese de no agregar al proyecto otra referencia de paquete de NuGet. En su lugar, permita que la referencia del SDK se resuelva mediante el paquete de extensión de Azure Functions. Use el SDK de Azure Cosmos DB por separado de los desencadenadores y enlaces.

Además, si va a crear manualmente su propia instancia del cliente del SDK de Azure Cosmos DB, debe seguir el patrón consistente en tener solo una instancia del cliente y usar una solución de patrón Singleton. Este proceso evitará posibles problemas con el socket en sus operaciones.

Escenarios comunes y soluciones alternativas

Se produce un error en la función de Azure con un mensaje de error que indica que la colección "doesn't exist"

La función de Azure emite el mensaje de error "O la colección de origen collection-name (en la base de datos database-name) o la colección de concesión collection2-name (en la base de datos database2-name) no existen. Ambas colecciones deben existir antes de que se inicia el agente de escucha. Para crear automáticamente la colección de concesiones, establezca CreateLeaseCollectionIfNotExists en true.

Este error significa que uno de los contenedores de Azure Cosmos DB (o los dos) que se requiere para que el disparador funcione:

  • No existe.
  • No es accesible para la función de Azure.

El propio texto del error le indica qué base de datos y contenedor de Azure Cosmos DB está buscando el desencadenador, en función de su configuración.

Para solucionar este problema:

  1. Compruebe el atributo Connection y que hace referencia a una configuración que existe en la aplicación de la función de Azure.

    • El valor de este atributo no debe ser la propia cadena de conexión, sino el nombre de la opción de configuración.

  2. Compruebe que los valores databaseName y containerName existen en su cuenta de Azure Cosmos DB.

    • Si usa el reemplazo de valor automático (mediante los patrones %settingName%), asegúrese de que el nombre de la configuración existe en la aplicación de la función de Azure.

  3. Si no especifica un valor LeaseContainerName/leaseContainerName, el valor predeterminado es leases. Compruebe que este contenedor existe.

    • Si lo desea, puede establecer el atributo CreateLeaseContainerIfNotExists en el desencadenador como true para crearlo automáticamente.

  4. Para asegurarse de que la cuenta de Azure Cosmos DB no está bloqueando la función de Azure, compruebe la configuración de firewall de la cuenta de Azure Cosmos DB.

La función de Azure no se puede iniciar, con el mensaje de error "Shared throughput collection should have a partition key"

Las versiones anteriores de la extensión de Azure Cosmos DB no permitían usar un contenedor de concesiones que se creaba dentro de una base de datos de rendimiento compartido.

Para solucionar este problema:

La función de Azure no se puede iniciar, con el mensaje de error "PartitionKey must be supplied for this operation"

Este error significa que actualmente está usando una colección de concesiones con particiones con una antigua dependencia de extensión.

Para solucionar este problema:

  • Actualice a la última versión disponible.

La función de Azure no se puede iniciar, con el mensaje de error "Forbidden (403); Substatus: 5300... The given request [POST ...] can't be authorized by Microsoft Entra token in data plane"

Este error significa que su función intenta realizar una operación que no es de datos mediante identidades de Microsoft Entra. No se puede usar CreateLeaseContainerIfNotExists = true cuando se usan identidades de Microsoft Entra.

La función de Azure no se puede iniciar, con el mensaje de error "The lease collection, if partitioned, must have partition key equal to id"

Este error significa que el contenedor de concesiones actual tiene particiones, pero la ruta de acceso de clave de partición no es /id.

Para solucionar este problema:

  • Vuelva a crear el contenedor de concesiones con /id como clave de partición.

Al intentar ejecutar el desencadenador, aparece el mensaje de error "Value can't be null. Parameter name: o" in your Azure function logs"

Este problema puede aparecer si usa Azure Portal e intenta seleccionar el botón Ejecutar al inspeccionar una función de Azure que usa el desencadenador. El desencadenador no requiere que seleccione Ejecutar para iniciarlo. Se inicia automáticamente al implementar la función.

Para solucionar este problema:

  • Para comprobar el flujo de registro de la función en Azure Portal, vaya a su contenedor supervisado e inserte algunos elementos nuevos. El desencadenador se ejecuta automáticamente.

Los cambios tardan demasiado tiempo en recibirse.

Este escenario puede tener varias causas. Considere la posibilidad de probar cualquiera de las soluciones siguientes (o todas):

  • ¿La función de Azure y la cuenta de Azure Cosmos DB se implementan en regiones independientes? Para que la latencia de red sea óptima, la función de Azure y su cuenta de Azure Cosmos DB deben estar colocadas en la misma región de Azure.

  • ¿Se producen los cambios en el contenedor de Azure Cosmos DB de forma continua o esporádica?

    • Si ocurre lo segundo, podría haber algún retraso entre los cambios que se almacenan y el momento en que la función de Azure los recoge. Este comportamiento se produce cuando el desencadenador comprueba internamente si hay cambios en el contenedor de Azure Cosmos DB y no encuentra ningún cambio en espera de lectura. A continuación, el desencadenador se suspende durante una cantidad de tiempo configurable (5 segundos, de forma predeterminada) antes de comprobar si hay nuevos cambios. El desencadenador utiliza este comportamiento para evitar un consumo elevado de unidades de solicitud (RU). Puede configurar este tiempo de suspensión en la opción FeedPollDelay/feedPollDelay de la configuración del desencadenador. Se espera que el valor esté en milisegundos.

  • El contenedor de Azure Cosmos DB podría tener una velocidad limitada.

  • Puede usar el atributo PreferredLocations en el desencadenador para especificar una lista separada por comas de las regiones de Azure y definir un orden personalizado preferido de conexión.

  • La velocidad a la que está procesando nuevos cambios viene determinada por la velocidad a la que el desencadenador recibe estos cambios. Compruebe el tiempo de ejecución de la función o la duración. Si la función es lenta, aumenta el tiempo que tarda el desencadenador en obtener nuevos cambios. Si observa un aumento reciente de la duración, es posible que un cambio reciente del código le esté afectando. Si la velocidad a la que recibe las operaciones en el contenedor de Azure Cosmos DB es más rápida que la velocidad del desencadenador, seguirá con retraso. Es posible que quiera investigar en el código de la función para determinar cuál es la operación que más tiempo consume y cómo optimizarla.

  • Puede usar registros de depuración para comprobar los diagnósticos y comprobar si hay retrasos en las redes.

Algunos cambios se repiten en el desencadenador.

El concepto de cambio es una operación en un elemento. Los escenarios más comunes en los que se reciben eventos para el mismo elemento son:

  • Se produce un error en la función durante la ejecución. Si la función ha habilitado directivas de reintento o en los casos en los que la ejecución de la función supera el tiempo de ejecución permitido, se puede volver a entregar el mismo lote de cambios a la función. Se espera este error y, por diseño, examine los registros de funciones para obtener una indicación de errores y asegurarse de que ha habilitado los registros de desencadenadores para obtener más detalles.

  • Hay un equilibrio de carga de concesiones entre instancias. Cuando las instancias aumentan o disminuyen, el equilibrio de carga puede provocar que se entregue el mismo lote de cambios a varias instancias de la función. Se espera este equilibrio de carga y, por diseño, debe ser transitorio. Los registros del desencadenador incluyen los eventos cuando una instancia adquiere y libera concesiones.

  • Se está actualizando un elemento. La fuente de cambios puede contener varias operaciones para el mismo elemento. Si el elemento recibe actualizaciones, puede recoger varios eventos (uno por cada actualización). Una manera fácil de distinguir entre las distintas operaciones del mismo elemento es realizar un seguimiento de la _lsnpropiedad para cada cambio. Si las propiedades no coinciden, los cambios son diferentes.

  • Si está identificando elementos solo por id, recuerde que el identificador único de un elemento es id y su clave de partición. (Dos elementos pueden tener el mismo valor de id, pero una clave de partición diferente).

Faltan algunos cambios en su desencadenador.

Es posible que vea que la función no recoge algunos de los cambios que se produjeron en el contenedor de Azure Cosmos DB for NoSQL. O que falten algunos cambios en el destino al copiarlos. Si es así, pruebe las soluciones de esta sección.

  • Asegúrese de que tiene los registros habilitados. Compruebe que no se producen errores durante el procesamiento.

  • Cuando la función de Azure recibe los cambios, a menudo los procesa y, opcionalmente, envía el resultado a otro destino. Cuando investigue los cambios que faltan, asegúrese de medir los cambios que se reciben en el punto de ingesta. Mida cuándo se inicia la función de Azure, no en el destino.

  • Si faltan algunos cambios en el destino, este comportamiento podría significar que se trata de algún error que sucede durante la ejecución de la función de Azure después de recibir los cambios.

    • En este caso, lo mejor es agregar bloques try/catch en el código y dentro de los bucles que puedan estar procesando los cambios. Esto le ayudará a detectar cualquier error para un subconjunto determinado de elementos y gestionarlo en consecuencia (puede enviarlo a otro almacenamiento para su posterior análisis o reintento). Como alternativa, puede configurar directivas de reintento de Azure Functions.

      Nota

      De forma predeterminada, el desencadenador de Azure Functions para Azure Cosmos DB for NoSQL no volverá a intentar un lote de cambios si se ha producido una excepción no controlada durante la ejecución del código. Esto significa que el motivo de que los cambios no hayan llegado al destino puede ser que no los haya procesado.

  • Si el destino es otro contenedor de Azure Cosmos DB y realiza operaciones upsert para copiar los elementos, compruebe la definición de la clave de partición en ambos contenedores. La clave de partición del contenedor supervisado y de destino debe ser la misma. Las operaciones upsert podrían guardar varios elementos de origen como uno solo en el destino debido a esta diferencia de configuración.

  • Si observa que el desencadenador no recibió algunos cambios, el escenario más común es que se ejecuta otra función de Azure. Es posible que la otra función se implemente en Azure o que una función se ejecute localmente en el equipo de un desarrollador con exactamente la misma configuración. Si es así, esta función podría estar robando un subconjunto de los cambios que esperaría que su función Azure procesara.

Además, el escenario se puede validar, si sabe cuántas instancias de la aplicación de función de Azure están ejecutándose. Si inspecciona el contenedor de concesiones y cuenta el número de elementos de concesión que contiene, los distintos valores de la propiedad Owner en ellos debería ser igual al número de instancias de la aplicación de función. Si hay más propietarios que instancias conocidas de la función de aplicaciones de Azure, estos propietarios adicionales son los que "roban" los cambios.

Una manera fácil de solucionar esta situación es aplicar LeaseCollectionPrefix/leaseCollectionPrefix a la función con un valor nuevo o diferente, o bien probar con un nuevo contenedor de concesiones.

Necesita reiniciar y volver a procesar todos los elementos del contenedor desde el principio.

Para volver a procesar todos los elementos de un contenedor desde el principio:

  1. Detenga la función de Azure si se está ejecutando actualmente.

  2. Elimine los documentos de la colección de concesiones (o elimine y vuelva a crear la colección de concesiones para que esté vacía).

  3. Establezca el atributo StartFromBeginning CosmosDBTrigger de su función en true.

  4. Reinicie la función de Azure. La función ahora lee y procesa todos los cambios desde el principio.

Cuando se establece StartFromBeginning en true, se indica a la función de Azure que comience a leer los cambios desde el principio del historial de la colección en lugar de desde la hora actual.

Esta solución solo funciona cuando no hay concesiones ya creadas (es decir, documentos en la colección de concesiones).

El establecimiento de esta propiedad en true cuando ya hay concesiones creadas no surte ningún efecto. En este escenario, cuando una función se detiene y se reinicia, comienza a leer desde el último punto de control, como se define en la colección de concesiones.

Error: Binding can be done only with IReadOnlyList<Document> or JArray

Este error se produce si el proyecto de Azure Functions contiene una referencia manual del paquete NuGet al SDK de Azure Cosmos DB con un conflicto de versión. Este error suele producirse porque el paquete tiene una versión diferente de la proporcionada por la extensión de Azure Cosmos DB para Azure Functions.

Para solucionar esta situación, quite la referencia manual de NuGet que se agregó y deje que la referencia del SDK de Azure Cosmos DB se resuelva con el paquete de la extensión de Azure Cosmos DB para Azure Functions.

Cambio del intervalo de sondeo de la función de Azure para detectar cambios

Como se explicó anteriormente en la sección Los cambios tardan demasiado tiempo en recibirse, la función de Azure se suspende durante un período configurable (5 segundos, de forma predeterminada) antes de comprobar si hay nuevos cambios (para evitar un consumo elevado de RU). Puede configurar este tiempo de suspensión en la opción FeedPollDelay/feedPollDelay de la configuración del desencadenador (el valor debe especificarse en milisegundos).

Contenido relacionado