Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Azure Functions proporciona extensiones de disparador y vinculación que se integran con varios servicios, principalmente servicios de Azure. La Extensión Connector amplía estas integraciones a una selección mucho más amplia de servicios, incluyendo sistemas empresariales y plataformas de datos.
Por ejemplo, utiliza el Conector Trigger para ejecutar una función cuando llega un nuevo correo en Office 365 Outlook, se crea un archivo en SharePoint o un registro cambia en Salesforce. El disparador recibe eventos de un conector gestionado en el espacio de nombres de Azure Connector. Para explorar los conectores gestionados disponibles, consulte la referencia de conectores.
Para más información sobre conectores gestionados, cuándo utilizarlos y disponibilidad de funciones, consulte Usar conectores gestionados en Azure Functions.
Note
Actualmente, el Connector Trigger no está soportado para este lenguaje.
Modos de entrega
Los conectores gestionados admiten dos modos de entrega:
-
Sondeo: El host de Funciones se conecta de salida al espacio de nombres del conector para recibir eventos. Configure
deliveryMode: 'Poll', y suministreconnectionytriggerConfigNameen las opciones de registro. -
Webhook: El espacio de nombres del conector envía eventos al endpoint de callback de la extensión. Webhook es el valor predeterminado cuando omites
deliveryMode.
Ambos modos admiten ayudantes con nombre como connectors.office365.onNewEmail y el ayudante genérico connectorTrigger . Para obtener ayuda para elegir un modo, consulte Elegir un modo de entrega.
Comenzar
Siga la ruta de configuración para su modo de entrega:
- Instale los paquetes Node.js y configure el paquete de extensiones.
- Crea o reutiliza un espacio de nombres y una conexión, y crea una configuración de disparador de sondeo.
- Obtén el endpoint de encuesta.
- Configura las credenciales del llamante, el acceso a la conexión y los ajustes locales o desplegados.
- Utiliza un ejemplo de encuesta a continuación, comparando sus
connectionvalorestriggerConfigNamecon tus ajustes.
La sondeación no requiere un endpoint público de callback ni una clave de sistema. Para la entrega por webhook, la función de destino y el endpoint de callback deben estar listos antes de crear la configuración del trigger.
Modos de entrega
Los conectores gestionados admiten dos modos de entrega:
-
Sondeo: El host de Funciones se conecta de salida al espacio de nombres del conector para recibir eventos. Establecer
delivery_mode=func.DeliveryMode.POLL, y suministrarconnectionytrigger_config_nameen@app.connector_trigger. -
Webhook: El espacio de nombres del conector envía eventos al endpoint de callback de la extensión. Webhook es el valor predeterminado cuando omites
delivery_modeen@app.connector_trigger.
Para obtener ayuda para elegir un modo, consulte Elegir un modo de entrega.
Comenzar
Siga la ruta de configuración para su modo de entrega:
- Instala los paquetes de Python y configura el paquete de extensiones.
- Crea o reutiliza un espacio de nombres y una conexión, y crea una configuración de disparador de sondeo.
- Obtén el endpoint de encuesta.
- Configura las credenciales del llamante, el acceso a la conexión y los ajustes locales o desplegados.
- Utiliza un ejemplo de encuesta a continuación, comparando sus
connectionvalorestrigger_config_namecon tus ajustes.
La sondeación no requiere un endpoint público de callback ni una clave de sistema. Para la entrega por webhook, la función de destino y el endpoint de callback deben estar listos antes de crear la configuración del trigger.
Modos de entrega
Los conectores gestionados admiten dos modos de entrega:
-
Sondeo: El host de Funciones se conecta de salida al espacio de nombres del conector para recibir eventos. Configura
DeliveryMode = ConnectorTriggerDeliveryMode.Poll, y añade la configuración de conexión y activa la configuración en[ConnectorTrigger]. -
Webhook: El espacio de nombres del conector envía eventos al endpoint de callback de la extensión. Webhook es el valor predeterminado cuando omites
DeliveryModeel[ConnectorTrigger]atributo.
Para obtener ayuda para elegir un modo, consulte Elegir un modo de entrega.
Comenzar
Siga la ruta de configuración para su modo de entrega:
- Instala la extensión.
- Crea o reutiliza un espacio de nombres y una conexión, y crea una configuración de disparador de sondeo.
- Obtén el endpoint de encuesta.
- Configura las credenciales del llamante, el acceso a la conexión y los ajustes locales o desplegados.
- Usa un ejemplo a continuación, comparando sus
ConnectionvaloresTriggerConfigNamecon tus configuraciones.
La sondeación no requiere un endpoint público de callback ni una clave de sistema. Para la entrega por webhook, la función de destino y el endpoint de callback deben estar listos antes de crear la configuración del trigger.
Examples
Los ejemplos de Office 365 Outlook y SharePoint Online utilizan cargas útiles fuertemente tipadas del SDK Azure Connectors. Para operaciones de conector que aún no tienen cargas útiles fuertemente tipadas, vincula para string recibir la carga útil JSON en bruto. Estos ejemplos registran intencionadamente solo información básica de la carga útil para mantener el foco en cómo definir funciones activadas por el conector. Sustituye el registro por la lógica de procesamiento de tu aplicación.
Para encontrar qué operaciones de conector soportan cargas útiles fuertemente tipadas para .NET, consulte Operaciones a Azure Functions signature mapping.
El modo de entrega de sondeos también soporta propiedades opcionales sobre el [ConnectorTrigger] atributo. Para descripciones, valores compatibles y valores predeterminados, consulte Propiedades de atributos de sondeo.
Office 365 Outlook
El siguiente ejemplo se ejecuta cuando llega un nuevo correo electrónico al buzón de Office 365 Outlook configurado:
Este ejemplo recibe lotes de hasta cuatro eventos conectores, cada uno con un correo electrónico, y se utiliza ConnectorEvent<T> para acceder a la carga útil de cada evento y MessageId.
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;
using Azure.Connectors.Sdk.Office365.Models;
namespace Office365App;
public sealed class O365Functions(ILogger<O365Functions> logger)
{
[Function("OnNewEmail")]
public void OnNewEmail(
[ConnectorTrigger(
DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
Connection = "ConnectorNamespace",
TriggerConfigName = "%OnNewEmailTriggerConfigName%",
IsBatched = true,
MaxBatchSize = 4,
TargetPendingEventThreshold = 16)]
ConnectorEvent<Office365OnNewEmailTriggerPayload>[] emails)
{
foreach (var email in emails)
{
var messageCount = email.Data.Body?.Value?.Count ?? 0;
logger.LogInformation(
"Poll event {MessageId}: received {MessageCount} new email message(s).",
email.MessageId,
messageCount);
}
}
}
Para desarrollo local, incluye la configuración de conexión y el nombre de configuración del disparador en la Values sección de local.settings.json:
{
"ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
"OnNewEmailTriggerConfigName": "<polling-trigger-config-name>"
}
Las propiedades del atributo hacen referencia a estas configuraciones:
-
Connection = "ConnectorNamespace"Identifica el prefijo de Configuración. La extensión lee el endpoint de sondeo desdeConnectorNamespace__pollingEndpoint. Para obtener el endpoint e información sobre las credenciales requeridas y las políticas de acceso, consulte Encuesta del endpoint. -
TriggerConfigName = "%OnNewEmailTriggerConfigName%"resuelve el valor de laOnNewEmailTriggerConfigNameconfiguración. Establezca su valor al nombre de la configuración del disparador de sondeo en tu espacio de nombres de conectores.
Los nombres del prefijo y de la configuración son ilustrativos; si los cambias, actualiza tanto las propiedades del atributo como la configuración para que coincidan. Para una aplicación de función desplegada, añade los mismos ajustes a los ajustes de la aplicación de funciones en lugar de local.settings.json.
El Office365OnNewEmailTriggerPayload tipo se define en el Azure.Connectors.Sdk.Office365.Models espacio de nombres.
Para la muestra completa de código, incluyendo infraestructura y registro de disparadores, véase Office 365 Outlook disparadores para .NET.
SharePoint Online
El siguiente ejemplo se ejecuta cuando se crea un archivo en la biblioteca de documentos configurada de SharePoint Online:
Este ejemplo recibe un evento conector que contiene un archivo por invocación (el valor predeterminado) y lo utiliza ConnectorEvent<T> para acceder a su carga útil y MessageId.
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;
using Azure.Connectors.Sdk.SharePointOnline.Models;
namespace SharePointApp;
public sealed class SharePointFunctions(ILogger<SharePointFunctions> logger)
{
[Function("OnNewFile")]
public void OnNewFile(
[ConnectorTrigger(
DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
Connection = "ConnectorNamespace",
TriggerConfigName = "%OnNewFileTriggerConfigName%")]
ConnectorEvent<SharePointOnlineOnNewFileItemsTriggerPayload> file)
{
var fileCount = file.Data.Body?.Value?.Count ?? 0;
logger.LogInformation(
"Poll event {MessageId}: received {FileCount} new SharePoint file(s).",
file.MessageId,
fileCount);
}
}
Para el desarrollo local, incluye estos valores en el Values objeto en local.settings.json:
{
"ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
"OnNewFileTriggerConfigName": "<polling-trigger-config-name>"
}
Las propiedades del atributo hacen referencia a estas configuraciones:
-
Connection = "ConnectorNamespace"Identifica el prefijo de Configuración. La extensión lee el endpoint de sondeo desdeConnectorNamespace__pollingEndpoint. Para obtener el endpoint e información sobre las credenciales requeridas y las políticas de acceso, consulte Encuesta del endpoint. -
TriggerConfigName = "%OnNewFileTriggerConfigName%"resuelve el valor de laOnNewFileTriggerConfigNameconfiguración. Establezca su valor al nombre de la configuración del disparador de sondeo de SharePoint en tu espacio de nombres de conectores.
Los nombres del prefijo y de la configuración son ilustrativos; si los cambias, actualiza tanto las propiedades del atributo como la configuración para que coincidan. Para una aplicación de función desplegada, añade los mismos ajustes a los ajustes de la aplicación de funciones en lugar de local.settings.json.
El SharePointOnlineOnNewFileItemsTriggerPayload tipo se define en el Azure.Connectors.Sdk.SharePointOnline.Models espacio de nombres.
Para el ejemplo completo de código, incluyendo infraestructura y registro de disparadores, véase SharePoint Online triggers para .NET.
Conector sin una carga útil fuertemente tipada
Algunos eventos de conector aún no tienen una carga útil .NET fuertemente tipada. El siguiente ejemplo se ejecuta cuando se añade un mensaje nuevo a un chat o canal de Microsoft Teams. El sondeo se utiliza ConnectorEvent<string> para recibir la carga útil JSON en bruto con metadatos de entrega; la entrega por webhook se vincula directamente a:string
Este ejemplo recibe un evento de conector por invocación (por defecto) y lo utiliza ConnectorEvent<string> para acceder a su carga útil JSON y MessageId.
using Microsoft.Azure.Functions.Worker;
using Microsoft.Azure.Functions.Worker.Extensions.Connector;
using Microsoft.Extensions.Logging;
namespace TeamsApp;
public sealed class TeamsFunctions(ILogger<TeamsFunctions> logger)
{
[Function("OnNewTeamsMessage")]
public void OnNewTeamsMessage(
[ConnectorTrigger(
DeliveryMode = ConnectorTriggerDeliveryMode.Poll,
Connection = "ConnectorNamespace",
TriggerConfigName = "%OnNewTeamsMessageTriggerConfigName%")]
ConnectorEvent<string> message)
{
logger.LogInformation(
"Poll event {MessageId}: received a Teams payload of {PayloadLength} characters.",
message.MessageId,
message.Data.Length);
}
}
Para el desarrollo local, incluye estos valores en el Values objeto en local.settings.json:
{
"ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
"OnNewTeamsMessageTriggerConfigName": "<polling-trigger-config-name>"
}
Las propiedades del atributo hacen referencia a estas configuraciones:
-
Connection = "ConnectorNamespace"Identifica el prefijo de Configuración. La extensión lee el endpoint de sondeo desdeConnectorNamespace__pollingEndpoint. Para obtener el endpoint e información sobre las credenciales requeridas y las políticas de acceso, consulte Encuesta del endpoint. -
TriggerConfigName = "%OnNewTeamsMessageTriggerConfigName%"resuelve el valor de laOnNewTeamsMessageTriggerConfigNameconfiguración. Establezca su valor al nombre de la configuración del disparador de sondeo de Teams en tu espacio de nombres de conectores.
Los nombres del prefijo y de la configuración son ilustrativos; si los cambias, actualiza tanto las propiedades del atributo como la configuración para que coincidan. Para una aplicación de función desplegada, añade los mismos ajustes a los ajustes de la aplicación de funciones en lugar de local.settings.json.
Para el ejemplo de código completo, incluyendo el registro de infraestructura y disparadores, consulte Disparadores genéricos de conector para .NET.
Mapeos de eventos de conectores
El nombre de la operación se define mediante el conector gestionado. Eliges el nombre de la función en tu código. Los ejemplos de sondeo y webhook utilizan los mismos nombres de evento, operación y función:
| Evento de conector | Nombre de la operación | Nombre de la función |
|---|---|---|
| Correo electrónico de nuevos Office 365 Outlook | OnNewEmailV3 |
OnNewEmail |
| Nuevo archivo de SharePoint Online | GetOnNewFileItems |
OnNewFile |
| Nuevo mensaje de chat o canal de Microsoft Teams | WebhookNewMessageTrigger |
OnNewTeamsMessage |
Las cargas útiles Webhook pueden contener múltiples elementos, dependiendo de la configuración del disparador.
La entrega por sondeo siempre habilita splitOn, de modo que cada evento en cola contiene un elemento dividido. Sin embargo, el modo de sondeo puede agrupar eventos en una única invocación de función configurando IsBatched = true. Para la configuración por lotes, consulte Atributos.
Tipos de enlaces
Para las funciones de trabajo aislado .NET, ambos modos de entrega admiten estos tipos de parámetros:
| Type | Description |
|---|---|
string |
Recibe el cuerpo del evento como JSON en bruto. Usa este tipo cuando no esté disponible un modelo SDK fuertemente tipado o cuando quieras deserializar la carga útil tú mismo. |
| Modelo de SDK de conectores | Desserializa el cuerpo del evento JSON en un modelo específico de operación a partir de Azure.Connectors.Sdk, como Office365OnNewEmailTriggerPayload o SharePointOnlineOnNewFileItemsTriggerPayload. |
| JSON-desserializable POCO | Desserializa el cuerpo del evento JSON en un tipo .NET cuya forma coincide con la carga útil del conector utilizando el serializador de trabajo configurado. |
ConnectorEvent<T> |
Envuelve un tipo de carga útil soportado en Data.
MessageId Contiene el identificador de entrega para sondeo y es null para la entrega por webhook. |
Parámetros de matriz
Los parámetros del array tienen significados diferentes en cada modo de entrega.
Para el sondeo, IsBatched determina la forma del parámetro de función, donde T es un tipo de carga útil de evento compatible:
IsBatched |
Tipo de parámetro de función |
|---|---|
false (valor predeterminado) |
T o ConnectorEvent<T> |
true |
T[] o ConnectorEvent<T>[], incluso cuando MaxBatchSize = 1 |
Establece MaxBatchSize un valor de 1 a 32; sin lote, el tamaño efectivo del lote debe ser 1. El tamaño del lote cuenta los eventos del conector, no los elementos dentro de la carga útil de un evento. El procesamiento por lotes no cambia el tipo de carga útil dentro de cada evento. La colección de Body.Value una carga útil de SDK es independiente del array externo de eventos suministrado a una invocación por lotes.
Para webhook, úsase T[] para deserializar el cuerpo del array JSON de una sola callback en un array de elementos de carga útil. Esto no es un lote de eventos entregados por separado. La entrega por Webhook procesa una callback por invocación; IsBatched se aplica únicamente a las sondeaciones.
Examples
La extensión del conector Node.js proporciona contextos tipados para las operaciones de Office 365 Outlook, SharePoint Online y Microsoft Teams mostradas en esta sección. Estos ejemplos registran intencionadamente solo información básica de la carga útil para mantener el foco en cómo definir funciones activadas por el Connector. Sustituye el registro por la lógica de procesamiento de tu aplicación.
Para encontrar qué operaciones de conector soportan cargas útiles fuertemente tipadas para JavaScript y TypeScript, consulte la referencia de extensión de conectorNode.js.
Office 365 Outlook
El siguiente ejemplo se ejecuta cuando llega un nuevo correo electrónico al buzón de Office 365 Outlook configurado:
Este ejemplo recibe hasta cuatro eventos de conector por invocación. El asistente proporciona los correos electrónicos de esos eventos como una sola lista.
import { InvocationContext } from '@azure/functions';
import {
connectors,
EmailTriggerContext,
} from '@azure/functions-extensions-connectors';
connectors.office365.onNewEmail('OnNewEmail', {
deliveryMode: 'Poll',
connection: 'ConnectorNamespace',
triggerConfigName: '%OnNewEmailTriggerConfigName%',
cardinality: 'many',
maxBatchSize: 4,
targetPendingEventThreshold: 16,
handler: async (
context: EmailTriggerContext,
invocationContext: InvocationContext,
) => {
invocationContext.log(
`Received ${context.emails.length} new email message(s).`,
);
},
});
El EmailTriggerContext tipo expone los mensajes como un array tipado emails .
Para ejemplos adicionales, consulte Office 365 Outlook desencadenantes para TypeScript.
SharePoint Online
El siguiente ejemplo se ejecuta cuando se crea un archivo en la biblioteca de documentos configurada de SharePoint Online:
Este ejemplo recibe un evento de conector por invocación, el valor predeterminado. El ayudante proporciona sus registros de propiedades de archivo como una lista.
import { InvocationContext } from '@azure/functions';
import {
connectors,
SharepointItemTriggerContext,
} from '@azure/functions-extensions-connectors';
connectors.sharepoint.onNewFileItems('OnSharepointNewFile', {
deliveryMode: 'Poll',
connection: 'ConnectorNamespace',
triggerConfigName: '%OnSharepointNewFileTriggerConfigName%',
handler: async (
context: SharepointItemTriggerContext,
invocationContext: InvocationContext,
) => {
invocationContext.log(
`Received ${context.records.length} new SharePoint file(s).`,
);
},
});
El SharepointItemTriggerContext tipo expone los registros de propiedades del archivo para records la GetOnNewFileItems operación. El ayudante conserva los campos suministrados por el conector sin convertirlos en un esquema de archivos fijo. Para ejemplos adicionales, consulte SharePoint Online triggers para TypeScript.
Equipos de Microsoft
El siguiente ejemplo se ejecuta cuando se añade un nuevo mensaje a un canal de Microsoft Teams:
Este ejemplo recibe un evento de conector por invocación, el valor predeterminado. El ayudante suministra su carga útil de mensajes como una lista.
import { InvocationContext } from '@azure/functions';
import {
ChannelMessageTriggerContext,
connectors,
} from '@azure/functions-extensions-connectors';
connectors.teams.onNewChannelMessage('OnNewChannelMessage', {
deliveryMode: 'Poll',
connection: 'ConnectorNamespace',
triggerConfigName: '%OnNewTeamsMessageTriggerConfigName%',
handler: async (
context: ChannelMessageTriggerContext,
invocationContext: InvocationContext,
) => {
invocationContext.log(
`Received ${context.messages.length} new Teams message(s).`,
);
},
});
El ChannelMessageTriggerContext tipo expone los mensajes como un array tipado messages .
Para ejemplos adicionales, consulte Microsoft Teams triggers para TypeScript.
Carga útil genérica del conector
Utilice el asistente genérico cuando una operación no tenga un registro con nombre. Accede context.rawPayload cuando tu código necesita procesar la carga original en sí.
Este ejemplo recibe un evento de conector por invocación, el valor predeterminado. El ayudante suministra sus elementos de carga útil en forma de lista.
import { InvocationContext } from '@azure/functions';
import {
connectorTrigger,
ConnectorTriggerContext,
} from '@azure/functions-extensions-connectors';
connectorTrigger('OnConnectorEvent', {
deliveryMode: 'Poll',
connection: 'ConnectorNamespace',
triggerConfigName: '%GenericTriggerConfigName%',
handler: async (
context: ConnectorTriggerContext,
invocationContext: InvocationContext,
) => {
invocationContext.log(`Received ${context.items.length} payload item(s).`);
},
});
El contexto genérico establece por defecto su tipo de elemento en unknown. Valida los elementos antes de acceder a las propiedades específicas de la operación.
context.rawPayload Conserva la entrada analizada antes de la normalización, incluyendo el array de eventos externo para la sondeación por lotes.
Examples
La extensión del conector Node.js proporciona contextos específicos del conector para las operaciones Office 365 Outlook, SharePoint Online y Microsoft Teams mostradas en esta sección. Estos ejemplos registran intencionadamente solo información básica de la carga útil para mantener el foco en cómo definir funciones activadas por el Connector. Sustituye el registro por la lógica de procesamiento de tu aplicación.
Para encontrar qué operaciones de conector soportan cargas útiles fuertemente tipadas para JavaScript y TypeScript, consulte la referencia de extensión de conectorNode.js.
Office 365 Outlook
El siguiente ejemplo se ejecuta cuando llega un nuevo correo electrónico al buzón de Office 365 Outlook configurado:
Este ejemplo recibe hasta cuatro eventos de conector por invocación. El asistente proporciona los correos electrónicos de esos eventos como una sola lista.
const {
connectors,
} = require('@azure/functions-extensions-connectors');
connectors.office365.onNewEmail('OnNewEmail', {
deliveryMode: 'Poll',
connection: 'ConnectorNamespace',
triggerConfigName: '%OnNewEmailTriggerConfigName%',
cardinality: 'many',
maxBatchSize: 4,
targetPendingEventThreshold: 16,
handler: async (context, invocationContext) => {
invocationContext.log(
`Received ${context.emails.length} new email message(s).`,
);
},
});
El contexto del manejador expone los mensajes a través del emails array.
SharePoint Online
El siguiente ejemplo se ejecuta cuando se crea un archivo en la biblioteca de documentos configurada de SharePoint Online:
Este ejemplo recibe un evento de conector por invocación, el valor predeterminado. El ayudante proporciona sus registros de propiedades de archivo como una lista.
const {
connectors,
} = require('@azure/functions-extensions-connectors');
connectors.sharepoint.onNewFileItems('OnSharepointNewFile', {
deliveryMode: 'Poll',
connection: 'ConnectorNamespace',
triggerConfigName: '%OnSharepointNewFileTriggerConfigName%',
handler: async (context, invocationContext) => {
invocationContext.log(
`Received ${context.records.length} new SharePoint file(s).`,
);
},
});
El contexto del manejador expone registros de propiedades de archivo para records la GetOnNewFileItems operación. El ayudante conserva los campos suministrados por el conector sin convertirlos en un esquema de archivos fijo.
Equipos de Microsoft
El siguiente ejemplo se ejecuta cuando se añade un nuevo mensaje a un canal de Microsoft Teams:
Este ejemplo recibe un evento de conector por invocación, el valor predeterminado. El ayudante suministra su carga útil de mensajes como una lista.
const {
connectors,
} = require('@azure/functions-extensions-connectors');
connectors.teams.onNewChannelMessage('OnNewChannelMessage', {
deliveryMode: 'Poll',
connection: 'ConnectorNamespace',
triggerConfigName: '%OnNewTeamsMessageTriggerConfigName%',
handler: async (context, invocationContext) => {
invocationContext.log(
`Received ${context.messages.length} new Teams message(s).`,
);
},
});
El contexto del manejador expone los mensajes a través del messages array.
Carga útil genérica del conector
Utilice el asistente genérico cuando una operación no tenga un registro con nombre. Accede context.rawPayload cuando tu código necesita procesar la carga original en sí.
Este ejemplo recibe un evento de conector por invocación, el valor predeterminado. El ayudante suministra sus elementos de carga útil en forma de lista.
const {
connectorTrigger,
} = require('@azure/functions-extensions-connectors');
connectorTrigger('OnConnectorEvent', {
deliveryMode: 'Poll',
connection: 'ConnectorNamespace',
triggerConfigName: '%GenericTriggerConfigName%',
handler: async (context, invocationContext) => {
invocationContext.log(`Received ${context.items.length} payload item(s).`);
},
});
Valida los elementos antes de acceder a las propiedades específicas de la operación.
context.rawPayload Conserva la entrada analizada antes de la normalización, incluyendo el array de eventos externo para la sondeación por lotes.
Configuraciones locales de encuesta
Añade los nombres de configuración del endpoint de sondeo y desencadenar a local.settings.json:
{
"IsEncrypted": false,
"Values": {
"ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
"OnNewEmailTriggerConfigName": "<outlook-polling-trigger-config-name>",
"OnSharepointNewFileTriggerConfigName": "<sharepoint-polling-trigger-config-name>",
"OnNewTeamsMessageTriggerConfigName": "<teams-polling-trigger-config-name>",
"GenericTriggerConfigName": "<generic-polling-trigger-config-name>"
}
}
El valor de connection: 'ConnectorNamespace' los ejemplos identifica el prefijo de configuración. Cada triggerConfigName expresión se resuelve a su configuración correspondiente de la aplicación. Para la configuración desplegada y los permisos de conexión, consulte Verificación de autenticación mediante sondeo.
Para otro ejemplo de registro en la encuesta, véase la muestra de encuestaNode.js.
Examples
Los ejemplos de Office 365 Outlook y SharePoint Online utilizan convertidores proporcionados por azurefunctions-extensions-connectors. El ejemplo genérico recibe JSON en bruto sin anotación del SDK. Estos ejemplos registran solo información básica de la carga útil; sustituye el registro por la lógica de procesamiento de tu aplicación.
Para encontrar qué operaciones de conector soportan cargas útiles fuertemente tipadas para Python, consulte Conceptos clave en la extensión del conector Python.
Office 365 Outlook
El siguiente ejemplo se ejecuta cuando llega un nuevo correo electrónico al buzón de Office 365 Outlook configurado:
Este ejemplo recibe hasta cuatro eventos de conector por invocación. El convertidor proporciona los correos electrónicos de esos eventos como una sola lista.
import logging
import azure.functions as func
import azurefunctions.extensions.connectors.office365 as office365
app = func.FunctionApp()
@app.function_name(name="OnNewEmail")
@app.connector_trigger(
arg_name="emails",
delivery_mode=func.DeliveryMode.POLL,
connection="ConnectorNamespace",
trigger_config_name="%OnNewEmailTriggerConfigName%",
cardinality=func.Cardinality.MANY,
max_batch_size=4,
target_pending_event_threshold=16,
)
def on_new_email(
emails: list[office365.GraphClientReceiveMessage],
) -> None:
logging.info(
"Received %s new email message(s).",
len(emails),
)
La GraphClientReceiveMessage vinculación soporta la OnNewEmailV3 operación. Para obtener código completo, infraestructura y registro de disparadores para ambos modos, consulte Office 365 Outlook disparadores para Python.
SharePoint Online
El siguiente ejemplo se ejecuta cuando se crea un archivo en la biblioteca de documentos configurada de SharePoint Online:
Este ejemplo recibe un evento de conector por invocación, el valor predeterminado. El convertidor proporciona sus registros de propiedades de archivo como una lista.
import logging
import azure.functions as func
import azurefunctions.extensions.connectors.sharepointonline as sharepoint
app = func.FunctionApp()
@app.function_name(name="OnSharepointNewFile")
@app.connector_trigger(
arg_name="files",
delivery_mode=func.DeliveryMode.POLL,
connection="ConnectorNamespace",
trigger_config_name="%OnSharepointNewFileTriggerConfigName%",
)
def on_sharepoint_new_file(files: list[sharepoint.Item]) -> None:
logging.info(
"Received %s new SharePoint file(s).",
len(files),
)
La Item vinculación soporta la GetOnNewFileItems operación y conserva las propiedades del archivo en dynamic_properties. Para obtener código completo, infraestructura y registro de disparadores para ambos modos, consulte SharePoint Online triggers para Python.
Carga útil genérica del conector
Utilice la azure-functions biblioteca para recibir eventos como cadenas JSON en bruto cuando una operación no tenga un convertidor tipado compatible, o cuando quiera analizar el JSON usted mismo.
Este ejemplo recibe un evento conector por invocación, el valor predeterminado, como cadena JSON en bruto.
import logging
import azure.functions as func
app = func.FunctionApp()
@app.function_name(name="OnConnectorEvent")
@app.connector_trigger(
arg_name="payload",
delivery_mode=func.DeliveryMode.POLL,
connection="ConnectorNamespace",
trigger_config_name="%GenericTriggerConfigName%",
)
def on_connector_event(payload: str) -> None:
logging.info("Received a connector event.")
Para ejemplos completos, consulte Desencadenantes genéricos de conector para Python.
Para el sondeo local, defina los nombres de configuración de endpoint y trigger en Valueslocal.settings.json:
{
"IsEncrypted": false,
"Values": {
"ConnectorNamespace__pollingEndpoint": "https://<connector-namespace-host>",
"OnNewEmailTriggerConfigName": "<outlook-polling-trigger-config-name>",
"OnSharepointNewFileTriggerConfigName": "<sharepoint-polling-trigger-config-name>",
"GenericTriggerConfigName": "<generic-polling-trigger-config-name>"
}
}
El valor de connection="ConnectorNamespace" los ejemplos identifica el prefijo de configuración. Cada trigger_config_name expresión se resuelve a su configuración correspondiente de la aplicación. Para la configuración desplegada y los permisos de conexión, consulte Verificación de autenticación mediante sondeo.
Tipos de enlaces
Ambos modos de entrega soportan las siguientes formas de registro y carga útil:
| Registration | Entrada del manejador |
|---|---|
app.connectorTrigger de @azure/functions |
Recibe la entrada de disparo original sin normalización auxiliar. El tipo de entrada TypeScript es unknownpor defecto ; para el sondeo por lotes, utilice un tipo de matriz como unknown[]. |
connectorTrigger de @azure/functions-extensions-connectors |
Recibe un ConnectorTriggerContext<T> con normalizado payload y items, analizado rawPayload, y toJSON() serialización. El tipo de elemento TypeScript es unknownpor defecto . |
Ayudantes nombrados como connectors.office365.onNewEmail |
Recibe el contexto normalizado con un array nombrado, como emails, , o messages, que usa itemsrecordsalias . TypeScript infiere el tipo de elemento SDK compatible. |
Los ayudantes aceptan entradas de objeto o cadenas JSON. Se normalizan { body: item } y { body: { value: [...] } } envuelven. Para encuestas agrupadas, aplanan la disposición exterior de sobres y sus elementos de carga útil en una sola items matriz, preservando el orden.
rawPayload conserva la entrada analizada antes de la normalización, incluyendo el array de eventos externo.
Configura cardinality: 'many' para habilitar el procesamiento por lotes de invocación. Un array en el contexto o un tipo de array TypeScript por sí solo no habilita el procesamiento por lotes.
maxBatchSize Cuenta los eventos del conector, no los elementos del array normalizado. Cada invocación de webhook gestiona una callback, que puede contener múltiples elementos de payload.
Los tipos TypeScript describen la carga útil esperada pero no validan ni transforman campos específicos de la operación en tiempo de ejecución. Valida la carga útil antes de acceder a las propiedades cuando su forma no sea conocida. Para registros tipados compatibles y tipos de carga útil SDK, consulte la referencia de extensión de conectorNode.js.
Tipos de enlaces
El disparador Connector soporta estos tipos de parámetros en Python:
| Type | Description |
|---|---|
str |
Recibe el cuerpo del evento como cadena JSON. |
dict |
Aceptado como anotación, pero el convertidor en bruto no analiza cadenas JSON en diccionarios. Para analizar JSON en bruto, vincula y str usa json.loads. |
bytes |
Recibe el cuerpo del evento como bytes en bruto. |
typing.List[str] o typing.List[bytes] |
Recibe eventos de conector entregados por separado como lista cuando el sondeo utiliza cardinality=func.Cardinality.MANY. Importa List desde typing para estas anotaciones. |
| Anotación del SDK de Conector soportada | Utiliza un convertidor registrado por azurefunctions-extensions-connectors para deserializar la carga útil en una lista de modelos SDK específicos para operaciones. |
Para enlaces SDK, anota el parámetro con el tipo de enlace compatible o una lista de ese tipo, como list[office365.GraphClientReceiveMessage]. Las ligaduras del SDK soportadas demuestran listas tanto para invocaciones de evento único como por lotes. Para el sondeo por lotes, el convertidor aplana los eventos de transporte y sus elementos de carga útil en una sola lista.
Configura cardinality=func.Cardinality.MANY el decorador para habilitar la invocación por lotes. Una anotación de lista por sí sola no habilita el procesamiento por lotes. La configuración de tamaño de lote cuenta los eventos del conector, no los elementos dentro de la carga útil de un evento ni el número de modelos en la lista devuelta.
El acceso a la conexión y la autorización de callback son separados. El Espacio de Nombres de Conector gestiona automáticamente su propio acceso a la conexión gestionada del conector. Configura el acceso de la aplicación de funciones según su modo de entrega.
Attributes
El ConnectorTrigger atributo admite las siguientes propiedades cuando DeliveryMode se establece en ConnectorTriggerDeliveryMode.Poll:
| Property | Required | Default | Description |
|---|---|---|---|
DeliveryMode |
Sí, para la votación | ConnectorTriggerDeliveryMode.Webhook |
Configurado para ConnectorTriggerDeliveryMode.Poll usar sondeo. |
Connection |
Yes | null |
Identifica el prefijo de configuración para el endpoint de sondeo del Espacio de Nombres del Conector y la configuración de identidad. Por ejemplo, "ConnectorNamespace" selecciona ConnectorNamespace__pollingEndpoint. |
TriggerConfigName |
Yes | null |
El nombre de la configuración del disparador de sondeo en el espacio de nombres del conector. Proporciona el nombre directamente o utiliza una expresión de configuración de aplicación como "%OnNewEmailTriggerConfigName%". |
IsBatched |
No | false |
Si cada invocación recibe un lote de eventos conectores. Cuando false, cada invocación recibe un evento. Configura y true utiliza un parámetro de matriz para recibir lotes. Los lotes se procesan uno a uno por oyente. |
MaxBatchSize |
No | 1 |
Eventos máximos de conectores por invocación, de 1 a 32. Cuando se omite o se establece en 0, utiliza la configuración del defaultMaxBatchSize host, que por defecto 1 se configura a salvo que se configure de otra manera en host.json. El tamaño efectivo del lote debe ser 1 cuando IsBatched es false. |
MaxConcurrentCalls |
No | 16 |
Máximo de tareas simultáneas de procesamiento de evento único por oyente en una instancia, incluyendo preparación, invocación y acuse de reconocimiento. Debe no ser negativo. Cuando se omite o se establece en 0, utiliza la configuración del defaultMaxConcurrentCalls host, que por defecto 16 se configura a salvo que se configure de otra manera en host.json. Solo se aplica cuando IsBatched es false. Las invocaciones agrupadas procesan un lote a la vez por cada oyente. |
TargetPendingEventThreshold |
No | 16 |
Número deseado de eventos pendientes de conectores por instancia para escalabilidad basada en destino. Debe no ser negativo. Cuando se omite o se establece en 0, utiliza la configuración del defaultTargetPendingEventThreshold host, que por defecto 16 se configura a salvo que se configure de otra manera en host.json. El tiempo de ejecución puede anular este objetivo de escalado. Esta propiedad no cambia el tamaño del lote ni la concurrencia de invocación. |
Para ver valores predeterminados a nivel de aplicación, consulte Configuración de host.json de sondeo. El tamaño del lote cuenta los eventos del conector, no los elementos dentro de la carga útil de un evento.
Decoradores de votación
Activar delivery_mode=func.DeliveryMode.POLL@app.connector_trigger y configurar la conexión de sondeo y la configuración del disparador:
| Parameter | Required | Default | Description |
|---|---|---|---|
arg_name |
Yes | None | Identifica el parámetro de función que recibe la carga útil. |
delivery_mode |
Sí, para la votación | func.DeliveryMode.WEBHOOK |
Configurado para func.DeliveryMode.POLL usar sondeo. Las cuerdas "Poll" y "Webhook" también están soportadas. |
connection |
Yes | None | Identifica el prefijo de configuración para el endpoint de sondeo y la configuración de identidad. Por ejemplo, "ConnectorNamespace" selecciona ConnectorNamespace__pollingEndpoint. |
trigger_config_name |
Yes | None | Identifica la configuración del disparador de sondeo. Proporciona el nombre directamente o utiliza una expresión de configuración de aplicación como "%OnNewEmailTriggerConfigName%". |
cardinality |
No | func.Cardinality.ONE |
Configura como func.Cardinality.MANY o "many" para habilitar la invocación por lotes. Las invocaciones agrupadas se procesan una a una por cada oyente. |
max_batch_size |
No | Opción predeterminada del anfitrión: 1 |
Eventos máximos de conectores por invocación, de 1 a 32. Cuando se omite o se establece en 0, se usa defaultMaxBatchSize de host.json. Sin lote, el tamaño efectivo del lote debe ser 1. |
max_concurrent_calls |
No | Opción predeterminada del anfitrión: 16 |
Máximo de tareas simultáneas de procesamiento de evento único por escuchador en una instancia. Cuando se omite o se establece en 0, se usa defaultMaxConcurrentCalls de host.json. Debe no ser negativo. No se aplica a invocaciones por lotes. |
target_pending_event_threshold |
No | Opción predeterminada del anfitrión: 16 |
Apunta a eventos pendientes por instancia para escalar basado en objetivos. Cuando se omite o se establece en 0, se usa defaultTargetPendingEventThreshold de host.json. Debe no ser negativo. No cambia el tamaño del lote ni la concurrencia de invocación; el tiempo de ejecución puede anular el objetivo de escalado. |
Para ver valores predeterminados a nivel de aplicación, consulte Configuración de host.json de sondeo. Para las formas de parámetros y las anotaciones del SDK, consulte Tipos de vinculación.
Opciones de registro en la votación
Configura deliveryMode: 'Poll' en un ayudante con nombre, el asistente genérico connectorTrigger , o app.connectorTrigger, y configura la conexión de sondeo y la configuración del disparador:
| Option | Required | Default | Description |
|---|---|---|---|
deliveryMode |
Sí, para la votación | 'Webhook' |
Configurado para 'Poll' usar sondeo. |
connection |
Yes | None | Identifica el prefijo de configuración para el endpoint de sondeo y la configuración de identidad. Por ejemplo, 'ConnectorNamespace' selecciona ConnectorNamespace__pollingEndpoint. |
triggerConfigName |
Yes | None | Identifica la configuración del disparador de sondeo. Proporciona el nombre directamente o utiliza una expresión de configuración de aplicación como '%OnNewEmailTriggerConfigName%'. |
cardinality |
No | 'one' |
Configura para 'many' habilitar el procesamiento por lotes de invocación. Las invocaciones agrupadas se procesan una a una por cada oyente. |
maxBatchSize |
No | Opción predeterminada del anfitrión: 1 |
Eventos máximos de conectores por invocación, de 1 a 32. Cuando se omite o se establece en 0, se usa defaultMaxBatchSize de host.json. Sin lote, el tamaño efectivo del lote debe ser 1. |
maxConcurrentCalls |
No | Opción predeterminada del anfitrión: 16 |
Máximo de tareas simultáneas de procesamiento de evento único por escuchador en una instancia. Cuando se omite o se establece en 0, se usa defaultMaxConcurrentCalls de host.json. Debe no ser negativo. No se aplica a invocaciones por lotes. |
targetPendingEventThreshold |
No | Opción predeterminada del anfitrión: 16 |
Apunta a eventos pendientes por instancia para escalar basado en objetivos. Cuando se omite o se establece en 0, se usa defaultTargetPendingEventThreshold de host.json. Debe no ser negativo. No cambia el tamaño del lote ni la concurrencia de invocación; el tiempo de ejecución puede anular el objetivo de escalado. |
Para ver valores predeterminados a nivel de aplicación, consulte Configuración de host.json de sondeo. Para formas de entrada de manejadores, consulte Tipos de enlace.
Punto de conexión de sondeo
La configuración de conexión de la función selecciona el prefijo del punto final de sondeo. Por ejemplo, el prefijo "ConnectorNamespace" utiliza ConnectorNamespace__pollingEndpoint. Define esta configuración bajo Values enlocal.settings.json para desarrollo local o en la configuración de la aplicación para una aplicación de función desplegada, como se muestra en los ejemplos de sondeo.
Recupere el endpoint de sondeo desde el portal de Espacios de Nombres de Conectores, o derive del servicio generado pollingEndpoints.receiveUri por la configuración del disparador de la siguiente manera. Sustituye los marcadores de posición por tus valores de recursos.
Requiere CLI de Azure, jq, y sed.
triggerConfigId="/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Web/connectorGateways/<namespace-name>/triggerConfigs/<trigger-config-name>"
triggerConfig=$(az rest --method get \
--url "${triggerConfigId}?api-version=2026-05-01-preview" \
--query '{receiveUri:properties.pollingEndpoints.receiveUri,name:name}' \
--output json)
receiveUri=$(printf '%s' "$triggerConfig" | jq -r '.receiveUri')
pollingEndpoint=$(printf '%s' "$receiveUri" |
sed -E 's#/(api/)?trigger[Cc]onfigs/[^/]+/receive$##')
triggerConfigName=$(printf '%s' "$triggerConfig" | jq -r '.name')
printf '%s\n' "ConnectorNamespace__pollingEndpoint=$pollingEndpoint" \
"OnNewEmailTriggerConfigName=$triggerConfigName"
Derive la configuración a partir del URI de recepción generado por el servicio de la siguiente manera:
Servicio pollingEndpoints.receiveUri |
<Connection>__pollingEndpoint |
|---|---|
https://<connector-namespace-host>/api/triggerconfigs/<name>/receive |
https://<connector-namespace-host> |
https://<host>/api/connectorGateways/<id>/triggerconfigs/<name>/receive |
https://<host>/api/connectorGateways/<id> |
Conserve el identificador de host y puerta de enlace proporcionado por el servicio; no adivines un nombre de host ni configure la URL de recepción completa, una ruta de operación, una base independiente /api o una cadena de consulta.
La extensión utiliza este endpoint con el nombre de configuración del disparador para construir las direcciones URL de las operaciones de sondeo. Para las credenciales y políticas de acceso necesarias para llamar a estas URLs, consulte Autenticación mediante sondeo.
Configuración del disparador de sondeo
El nombre de configuración del disparador de la función identifica la configuración de la que se deben recibir eventos.
Sondeo de los valores de configuración de los disparadores
| Valor de configuración | Description |
|---|---|
| Conexión | La conexión autorizada por conectores gestionados, como Office 365 Outlook o SharePoint Online. Esto es independiente de la configuración de conexión de la función, que identifica un prefijo de configuración de la aplicación. |
| Nombre de la operación | La operación de disparo del conector, como OnNewEmailV3 o GetOnNewFileItems. |
| Parameters | Valores requeridos por la operación, como una carpeta de Outlook o una biblioteca de SharePoint y documentos. |
| Nombre de configuración del disparador | El nombre de esta configuración de disparador de sondeo, referenciado directamente por la función o a través de una configuración de la aplicación. |
| Modo de entrega | Cómo se entregan los eventos desde los servicios, mediante encuestas o modo webhook. |
Crear una configuración de disparador de sondeo
Si aún no tienes un espacio de nombres de conectores, crea un espacio de nombres de conectores.
Ve al portal de Espacio de Nombres de Conectores y luego selecciona tu espacio de nombres.
En el menú de espacio de nombres, selecciona Triggers y luego selecciona Crear.
Encuentra el conector gestionado que quieres usar y luego selecciona el evento que debería activar la función.
En la página de configuración del disparador, crea una conexión o selecciona una conexión existente. Crear una conexión requiere una autenticación única con el servicio externo.
Proporciona las aportaciones requeridas para el evento. Por ejemplo, el evento de Office 365 Outlook nuevo correo requiere que la carpeta vigile los mensajes nuevos.
Para el tipo de destino, elige Azure Functions.
Para el modo de entrega, elige Sondeo.
Revise la configuración y luego seleccione Crear.
Autenticación por sondeo
Para el sondeo, conceda una política de acceso a nivel de conexión a la identidad administrada de la aplicación de función (desplegada) o a su identidad de desarrollador (local). El anfitrión de Funciones utiliza las credenciales Microsoft Entra de esta identidad para recibir y confirmar eventos a través del endpoint de sondeo. El acceso a la conexión propio del Espacio de Nombres de Conector se gestiona automáticamente.
La política del llamante concede acceso a la conexión gestionada del conector, no al espacio de nombres en sí. Iniciar sesión o habilitar una identidad gestionada no otorga este acceso automáticamente al llamante.
A diferencia de la entrega por webhook, el sondeo no requiere una URL pública de callback ni una clave del sistema de la aplicación de función porque la aplicación de funciones recupera eventos del espacio de nombres en lugar de recibir callbacks.
Los ajustes de autenticación en las subsecciones siguientes utilizan el prefijo ConnectorNamespace, coincidiendo con los ejemplos de disparador. Si tu función usa un prefijo diferente para configurar la conexión, usa ese prefijo en su lugar.
Conceder políticas de acceso
Utilice cualquiera de los dos métodos para conceder al llamante de sondeo acceso a la conexión. Necesitas permiso para gestionar las políticas de acceso en la conexión. Utilice el ID principal (objeto) del llamante, no su ID de aplicación (cliente).
- Ve al portal de Espacio de Nombres de Conectores y luego selecciona tu espacio de nombres.
- Abra Conexiones y seleccione la conexión de conector gestionada utilizada por su configuración de disparador de sondeo.
- Abre la pestaña Políticas de acceso de la conexión.
- Añade una política de acceso para la identidad del llamante. Para el desarrollo local, utiliza el ID de objeto de tu cuenta de desarrollador. Para una aplicación de función desplegada, utilice el ID principal (objeto) de la identidad gestionada que utiliza su aplicación.
- Verifique que el llamante tenga una política de acceso en la conexión.
Desarrollo local
- Inicia sesión con tu identidad de desarrollador, por ejemplo ejecutando
az login. Esta es la cuenta de Microsoft Entra que la extensión utiliza para autenticar las solicitudes de sondeo localmente. - Conceda una política de acceso a la conexión del conector gestionado para esa identidad. Iniciar sesión solo no otorga acceso a la conexión.
- Define la configuración de conexión en
Valueslocal.settings.json. OmitirConnectorNamespace__credentialusar credenciales de desarrollador.
Aplicación de funciones desplegadas
- Active una identidad administrada asignada por el sistema en la aplicación de funciones, o asigne una identidad administrada asignada por el usuario.
- Conceda una política de acceso a la conexión del conector gestionado para esa identidad.
- Configure los siguientes ajustes de autenticación en los ajustes de la aplicación de funciones:
| Configuración de aplicación | Value |
|---|---|
ConnectorNamespace__credential |
managedidentity |
ConnectorNamespace__clientId |
El ID de cliente de la identidad administrada asignada por el usuario a utilizar para el sondeo. Configura solo cuando se utiliza una identidad asignada por el usuario. |
Alternativamente, establezca ConnectorNamespace__managedIdentityResourceId el ID de recurso de la identidad asignada por el usuario en lugar de configurar ConnectorNamespace__clientId. Para una identidad asignada por el sistema, omita ambos selectores.
Uso en encuestas
El host de Funciones se conecta hacia el exterior al espacio de nombres del conector para consultar eventos y reconocer invocaciones exitosas. La extensión pasa los eventos a tu función; no escribes un bucle de sondeo.
La entrega es al menos una vez. Las invocaciones fallidas no se reconocen, y los eventos pueden volver a entregarse después de que expire el bloqueo gestionado por el servicio. Hacer que el procesamiento sea idempotente.
Si lo usas ConnectorEvent<T>.MessageId para deduplicación, asigna el ámbito al espacio de nombres y a la configuración del disparador; no des por hecho que los IDs de los mensajes son únicos entre los disparadores.
Establece DeliveryMode = ConnectorTriggerDeliveryMode.Poll en [ConnectorTrigger], y proporciona las Connection propiedades y TriggerConfigName . Consulta los ejemplos de encuestas.
Para propiedades de atributos, valores compatibles y valores predeterminados, consulte Encuestar propiedades de atributos.
Establece delivery_mode=func.DeliveryMode.POLL en @app.connector_trigger, y suministra connection y trigger_config_name. Consulta los ejemplos de encuestas.
El host recibe un evento por invocación a menos que cardinality=func.Cardinality.MANY active el procesamiento por lotes. Para lotes en bruto, use typing.List[str] o typing.List[bytes]; las anotaciones del SDK soportado proporcionen una lista de modelos. Para opciones, valores soportados y valores predeterminados, consulte Decoradores de encuestas.
Configure deliveryMode: 'Poll', y suministre connection y triggerConfigName en las opciones de registro. Consulta los ejemplos de encuestas.
El host recibe un evento por invocación a menos que cardinality: 'many' active el procesamiento por lotes. Los ayudantes nombrados y genéricos combinan los elementos de la carga útil de todos los eventos en un único contexto. Los manejadores directos app.connectorTrigger reciben en cambio el array de eventos externo. Para opciones, valores compatibles y valores predeterminados, consulte Opciones de registro de sondeo.
Escalado y simultaneidad
Entrega por Webhook
En modo webhook, el espacio de nombres del conector envía solicitudes HTTP al punto final de callback de la extensión. Los disparadores de conector escalan igual que los HTTP, según el comportamiento y los límites de escalado HTTP del plan de alojamiento. Para más detalles, consulte Escalado basado en eventos en Azure Functions.
Entrega de encuestas
En modo de sondeo, el Conector Trigger utiliza escalado basado en destino basado en el atraso estimado de eventos para la configuración del trigger en el Espacio de Nombres del Conector. El objetivo de escalado es independiente de la concurrencia de procesamiento por instancia y del tamaño del lote. Para la ecuación de escalado, los ajustes de configuración y las guías de ajuste, consulte Escalado basado en objetivos de conectores gestionados.
Registration
Usa la función genérica connectorTrigger para una operación que no tenga un registro específico del conector:
import { InvocationContext } from '@azure/functions';
import {
connectorTrigger,
ConnectorTriggerContext,
} from '@azure/functions-extensions-connectors';
connectorTrigger('OnConnectorEvent', {
handler: async (
context: ConnectorTriggerContext,
invocationContext: InvocationContext,
) => {
invocationContext.log(JSON.stringify(context.rawPayload));
},
});
El registro genérico predetermina el tipo de artículo a unknown. Valida la carga útil antes de acceder a las propiedades específicas de cada operación. Configura el conector, la operación, los parámetros de operación, la función de destino y la autenticación de callback en la configuración de disparadores en el espacio de nombres de Azure Connector.
Registration
Usa la función genérica connectorTrigger para una operación que no tenga un registro específico del conector:
const {
connectorTrigger,
} = require('@azure/functions-extensions-connectors');
connectorTrigger('OnConnectorEvent', {
handler: async (context, invocationContext) => {
invocationContext.log(JSON.stringify(context.rawPayload));
},
});
El registro genérico normaliza el sobre de callback pero no valida la forma específica de la carga útil de la operación. Valida la carga útil antes de acceder a las propiedades específicas de cada operación. Configura el conector, la operación, los parámetros de operación, la función de destino y la autenticación de callback en la configuración de disparadores en el espacio de nombres de Azure Connector.
Decoradores
Aplica connector_trigger a la función que recibe la carga útil del evento:
import azure.functions as func
app = func.FunctionApp()
@app.function_name(name="OnConnectorEvent")
@app.connector_trigger(arg_name="payload")
def on_connector_event(payload: str) -> None:
# Process the raw JSON payload.
pass
El arg_name valor identifica el parámetro de función que recibe la carga útil. Configura el conector, la operación, los parámetros de operación, la función de destino y la autenticación de callback en la configuración de disparadores en el espacio de nombres de Azure Connector.
Attributes
A diferencia de las sondeaciones, la entrega por webhook no requiere propiedades adicionales sobre el [ConnectorTrigger] atributo porque webhook es el modo de entrega predeterminado. También puedes establecer DeliveryMode = ConnectorTriggerDeliveryMode.Webhook explícitamente. Las propiedades específicas de las encuestas no se aplican a la entrega por webhook.
Configuración del desencadenador de webhook
La URL de callback de la configuración del disparador identifica la función de destino.
Valores de configuración de disparadores Webhook
| Valor de configuración | Description |
|---|---|
| Conexión | La conexión autorizada por conectores gestionados, como Office 365 Outlook o SharePoint Online. |
| Nombre de la operación | La operación de disparo del conector, como OnNewEmailV3 o GetOnNewFileItems. |
| Parameters | Valores requeridos por la operación, como una carpeta de Outlook o una biblioteca de SharePoint y documentos. |
| URL de devolución de llamada | El punto final webhook de la extensión Connector para la función de destino. Consulte autenticación Webhook. |
| Nombre de la función | El nombre de la función registrada en tu código de app. |
| Authentication | La configuración de autenticación utilizada para llamar a la aplicación de función. |
El functionName valor de la cadena de consulta en la URL de callback debe coincidir con el nombre de la función registrada. Los nombres válidos de funciones webhook contienen de 1 a 128 letras, números, guiones bajos o guións.
Crear una configuración de disparador webhook
Crea una configuración de disparador usando CLI de Azure o el portal Connector Namespace.
Configurar el desencadenador
Una configuración de disparador en Azure Connector Namespace asocia un evento de servicio externo con la función de devolución de destino.
Valores de configuración de disparadores
| Valor de configuración | Description |
|---|---|
| Conexión | La conexión autorizada por conectores gestionados, como Office 365 Outlook o SharePoint Online. |
| Nombre de la operación | La operación de disparo del conector, como OnNewEmailV3 o GetOnNewFileItems. |
| Parameters | Valores requeridos por la operación, como una carpeta de Outlook o una biblioteca de SharePoint y documentos. |
| URL de devolución de llamada | El punto final webhook de la extensión Connector para la función de destino. Consulte autenticación Webhook. |
| Nombre de la función | El nombre de la función registrada en tu código de app. |
| Authentication | La configuración de autenticación utilizada para llamar a la aplicación de función. |
El functionName valor de la cadena de consulta en la URL de callback de la configuración del disparador debe coincidir con el nombre de la función registrada. Los nombres válidos de funciones contienen de 1 a 128 letras, números, guiones bajos o guiones.
El nombre de la operación se define mediante el conector gestionado. Eliges el nombre de la función en tu código, y la configuración del disparador asigna la operación a esa función. Los ejemplos de este artículo utilizan estos mapeos:
| Evento de conector | Nombre de la operación | Nombre de la función |
|---|---|---|
| Correo electrónico de nuevos Office 365 Outlook | OnNewEmailV3 |
OnNewEmail |
| Nuevo archivo de SharePoint Online | GetOnNewFileItems |
OnSharepointNewFile |
| Nuevo mensaje del canal de Microsoft Teams | OnNewChannelMessage |
OnNewChannelMessage |
| Evento de conector seleccionado | La operación seleccionada en la configuración del disparador | OnConnectorEvent |
| Evento de conector | Nombre de la operación | Nombre de la función |
|---|---|---|
| Correo electrónico de nuevos Office 365 Outlook | OnNewEmailV3 |
OnNewEmail |
| Nuevo archivo de SharePoint Online | GetOnNewFileItems |
OnSharepointNewFile |
| Evento de conector seleccionado | La operación seleccionada en la configuración del disparador | OnConnectorEvent |
Crear una configuración de disparador
Crea una configuración de disparador usando CLI de Azure o el portal Connector Namespace.
Antes de que la extensión pueda recibir un evento, crea estos recursos y configuraciones:
- Un espacio de nombres de conectores.
- Una conexión conectora gestionada autorizada para acceder al servicio externo.
- Una configuración de disparador que selecciona el evento del conector, los parámetros de operación y el modo de entrega.
Para la entrega por webhook, la configuración del disparador también incluye la URL de callback y la autenticación de callback.
Las configuraciones de disparador son recursos de Espacio de Nombres de Conector que también puedes desplegar a través de ARM o Bicep.
Los ejemplos de CLI de Azure a continuación utilizan una aplicación de funciones desplegada. Despliega la aplicación con la extensión y la función de destino antes de ejecutarlas.
El siguiente ejemplo de Bash utiliza CLI de Azure y jq para crear un disparador Office 365 Outlook nuevo correo electrónico. Sustituye los valores provisionales de tus recursos y conexión:
resourceGroup="<RESOURCE_GROUP>"
namespaceName="<CONNECTOR_NAMESPACE>"
functionAppName="<FUNCTION_APP>"
functionName="OnNewEmail"
triggerName="<TRIGGER_NAME>"
connectionName="<CONNECTION_NAME>"
connectorName="office365"
operationName="OnNewEmailV3"
subscriptionId=$(az account show --query id --output tsv)
connectorKey=$(az functionapp keys list \
--resource-group "$resourceGroup" \
--name "$functionAppName" \
--query "systemKeys.connector_extension" \
--output tsv)
callbackUrl="https://${functionAppName}.azurewebsites.net/runtime/webhooks/connector?functionName=${functionName}"
notificationFile=$(mktemp)
trap 'rm -f "$notificationFile"' EXIT
jq -n \
--arg callbackUrl "$callbackUrl" \
--arg connectorKey "$connectorKey" \
'{
callbackUrl: $callbackUrl,
authentication: {
type: "QueryString",
name: "code",
value: $connectorKey
}
}' > "$notificationFile"
az connector-namespace trigger create \
--resource-group "$resourceGroup" \
--namespace "$namespaceName" \
--name "$triggerName" \
--connection-details "{connectionName:${connectionName},connectorName:${connectorName}}" \
--operation-name "$operationName" \
--parameters "[{name:folderPath,value:'Inbox'}]" \
--notification-details "@$notificationFile" \
--description "${connectorName} ${operationName} -> ${functionName}" \
--metadata "{destinationType:functionApp,functionAppName:${functionAppName},functionAppResourceGroup:${resourceGroup},functionAppSubscriptionId:${subscriptionId},functionName:${functionName},recurrenceFrequency:Minute,recurrenceInterval:'5'}"
rm -f "$notificationFile"
trap - EXIT
El --parameters valor es específico para la operación del conector. En este ejemplo, folderPath selecciona la carpeta Outlook para monitorizar. La URL de callback no contiene la clave del sistema. El notificationDetails.authentication objeto añade la clave como un secreto de cadena de consulta cuando el Espacio de Nombres del Conector invoca la función.
Autenticación por Webhook
El espacio de nombres del conector envía eventos a la aplicación de funciones, en lugar de que la aplicación de función haga sondeo al espacio de nombres. Por defecto, el host de Funciones autentica estas callbacks validando la clave del sistema de la extensión del Connector, llamada connector_extension.
El Espacio de Nombres de Conectores gestiona automáticamente el acceso a su conexión de conector gestionada. A diferencia del sondeo, la identidad de la aplicación de función no necesita una política de acceso a conexión únicamente para recibir llamadas de enlace webhook; la tecla del sistema autoriza esas solicitudes a la aplicación de funciones.
Webhook callback URL
Aplicación desplegada
Utilice el endpoint de callback de la extensión, sin una clave en la URL:
https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>
El functionName valor debe coincidir con el nombre de la función registrada: el [Function] atributo en C#, el @app.function_name decorador en Python o el registro del disparador en Node.js.
Para una aplicación desplegada que utilice autenticación predeterminada, utilice la tecla de sistema de connector_extension la extensión Connector, no una tecla de función individual. Después de desplegar la aplicación de funciones con la extensión, recupere la clave del sistema:
az functionapp keys list \
--resource-group <RESOURCE_GROUP> \
--name <FUNCTION_APP_NAME> \
--query "systemKeys.connector_extension" \
--output tsv
En la configuración del disparador, guarda la clave en notificationDetails.authentication, por separado de la URL de devolución de llamada:
{
"notificationDetails": {
"callbackUrl": "https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>",
"authentication": {
"type": "QueryString",
"name": "code",
"value": "<CONNECTOR_EXTENSION_KEY>"
}
}
}
Al entregar un evento, el espacio de nombres del conector añade la clave como code parámetro query-string. Mantener la clave separada de la URL de callback guardada permite al portal enmascararla como un secreto. No incluyas la clave en la URL guardada de callback ni la confirmes en control de versiones.
Las configuraciones de disparadores existentes que incluyen la clave en la URL de devolución de llamada siguen funcionando. Cuando editas y guardas una configuración de trigger existente, la clave se mueve a notificationDetails.authentication.
No se pueden asignar a las claves del sistema por disparador y requieren una rotación coordinada entre la aplicación de funciones y el espacio de nombres del conector. Para callbacks basados en identidad sin clave compartida, consulte Autenticación integrada.
Desarrollo local de webhooks
Las devoluciones de llamada Webhook deben llegar a su host de Funciones en ejecución desde el espacio de nombres del Conector. Cuando ejecutas localmente:
Inicie la aplicación de funciones con Azure Functions Core Tools, habilitando la autorización:
func start --enableAuthImportante
Úsalo
--enableAuthsiempre al exponer tu app a través de un túnel de desarrollo. Sin él, tu endpoint de función queda completamente sin autenticación en la red pública.Utilice un túnel de desarrollo de Microsoft para reenviar un endpoint HTTPS público al puerto host local de Functions. Configura la visibilidad del puerto del túnel en Público para que el espacio de nombres del conector pueda acceder a él.
Construya la URL de callback con el nombre de host del túnel y el nombre de la función registrada, y úsalo en la configuración del disparador webhook. Por ejemplo, un puerto de reenvío de túnel 7071 a la
OnNewFilefunción utiliza una URL como:https://<tunnel-id>-7071.usw2.devtunnels.ms/runtime/webhooks/connector?functionName=OnNewFilePara un host local que almacene secretos en Azurite, recupere su
connector_extensionclave del sistema utilizando estos comandos de PowerShell. Configurado$connStra la conocida cadena de conexión de Azurite:$connStr = "<azurite-connection-string>" # Find the most recent host.json blob $blobs = az storage blob list --container-name azure-webjobs-secrets --connection-string $connStr -o json | ConvertFrom-Json $blobName = ($blobs | Where-Object { $_.name -match '(^|/)host\.json$' } | Sort-Object { $_.properties.lastModified } | Select-Object -Last 1).name # Download and parse az storage blob download --container-name azure-webjobs-secrets --name $blobName --connection-string $connStr --file host-keys.json --no-progress $keys = Get-Content host-keys.json | ConvertFrom-Json $connectorKey = ($keys.systemKeys | Where-Object { $_.name -eq "connector_extension" }).value Remove-Item -LiteralPath host-keys.jsonGuarde la clave de sistema del
connector_extensionhost local por separado ennotificationDetails.authentication, utilizando elQueryStringformato de autenticación mostrado arriba.Mantén el host y el túnel funcionando durante las pruebas. Actualice la configuración del disparador si cambia el nombre de host del túnel.
Autenticación integrada
Para llamadas de enlace web sin claves compartidas, utilice autenticación integrada por App Service (también llamada Easy Auth) con una identidad gestionada. Esta configuración es independiente del lenguaje de programación de la función.
El Espacio de Nombres del Conector utiliza su identidad administrada asignada por el sistema o el usuario para solicitar un token de Microsoft Entra ID para cada callback. La autenticación integrada valida el token y la identidad del llamante antes de que la solicitud llegue al host de Funciones. Para una implementación de extremo a extremo sin secretos de cliente, consulte el ejemplo de autenticación integrada.
Esta sección cubre la autenticación desde el espacio de nombres hacia la aplicación de funciones. El Espacio de Nombres de Conectores gestiona automáticamente el acceso a su conexión de conector gestionada. Para la autenticación de los servicios ascendentes, consulte la visión general de los conectores de Azure.
Configuración de la aplicación de funciones
Importante
Esta configuración requiere autenticación en toda la aplicación de funciones, no solo /runtime/webhooks/connectoren , y restringe el acceso a la identidad de callback del espacio de nombres. Las funciones HTTP existentes que requieren teclas de función continúan requiriendo esas teclas además de la autenticación a nivel de aplicación. Antes de aplicar esta configuración a una aplicación existente, asegúrese de que los clientes de API y las sondas de estado puedan cumplir con la política de autenticación y autorización a nivel de aplicación y cualquier requisito de clave a nivel de función. De lo contrario, las solicitudes pueden fallar con HTTP 401 o 403. Si la aplicación debe aceptar a otros llamadores, adapta la política de autorización en lugar de copiar esta lista de permisos sin cambios. Para opciones de política, consulte Configurar la autorización de Microsoft Entra.
Configura la autenticación integrada a través del recurso ARM deauthsettingsV2 la aplicación de funciones o su equivalente en Bicep. El ejemplo utiliza las siguientes configuraciones clave:
| Setting | Purpose |
|---|---|
platform.enabled: true |
Activa la autenticación integrada. |
globalValidation.requireAuthentication: true |
Requiere autenticación antes de que las solicitudes lleguen al host de Funciones. |
globalValidation.unauthenticatedClientAction: Return401 |
Devuelve HTTP 401 para callbacks no autenticados en lugar de redirigirlo a una página de inicio de sesión. |
identityProviders.azureActiveDirectory.enabled: true |
Activa la validación del token Microsoft Entra. |
registration.clientId |
El ID de la aplicación (cliente) del registro de la aplicación Microsoft Entra que representa la aplicación de función. |
registration.openIdIssuer |
Dirección URL del emisor del inquilino: https://login.microsoftonline.com/{tenantId}/v2.0. |
validation.allowedAudiences |
Identificador de cliente e identificador URI de la aplicación Entra. Los tokens deben tener una audiencia permitida en la aud reivindicación. |
validation.defaultAuthorizationPolicy.allowedPrincipals.identities |
Los IDs del objeto (principal) permitían llamar a la aplicación de función. El ejemplo permite únicamente la identidad gestionada de callback del espacio de nombres. Adapta esta política si tu app tiene otras personas que llaman. Un token válido con una oid reclamación no incluida en la lista de permitidos es denegado con HTTP 403. |
Los registration ajustes y validation en esta tabla están bajo identityProviders.azureActiveDirectory.
El ejemplo también asigna una identidad administrada asignada por el usuario a la aplicación de funciones y la federa al registro de la aplicación Entra. La autenticación integrada utiliza esta credencial de identidad federada para obtener aserciones de cliente sin almacenar un secreto de cliente. El ejemplo establece la configuración OVERRIDE_USE_MI_FIC_ASSERTION_CLIENTID de la aplicación al ID de cliente de la identidad de la función y se establece registration.clientSecretSettingName al nombre de esa configuración.
La identidad de la aplicación de función utilizada para la federación es independiente de la identidad de callback del espacio de nombres. La identidad del espacio de nombres es el llamante permitido por allowedPrincipals.identities.
Una vez configurada la autenticación integrada para validar las devoluciones de llamada, desactive la verificación redundante de clave del sistemahost.json:
{
"version": "2.0",
"extensions": {
"connector": {
"system": {
"webhookAuthorizationLevel": "Anonymous"
}
}
}
}
Úsalo Anonymous solo cuando otra capa de autenticación valida las solicitudes antes de que lleguen al host de Funciones. Esta configuración no habilita la validación de tokens por sí sola.
Configuración del espacio de nombres del conector
Habilite una identidad administrada asignada por el sistema en el Espacio de Nombres del Conector, o añéguele una identidad asignada por el usuario. En la configuración notificationDetails.authenticationdel disparador , establezca:
| Property | Value |
|---|---|
type |
ManagedServiceIdentity |
audience |
El ID de cliente del registro de la app Entra, que coincide con una audiencia aceptada por la aplicación de funcións. |
identity |
El ID de recurso de la identidad administrada asignada por el usuario adjunto. Omite esta propiedad para una identidad asignada por el sistema. |
El espacio de nombres utiliza esa identidad para obtener un token y lo envía en el encabezado del Authorization: Bearer <token> callback. El token iss identifica al inquilino, aud identifica la aplicación de destino e oid identifica la identidad gestionada del espacio de nombres.
El espacio de nombres gestiona automáticamente su propio acceso a la conexión gestionada del conector. Este acceso es independiente de la autorización de callback, que configuras mediante autenticación integrada en la aplicación de funciones.
Flujo de autenticación y validación
- El Espacio de Nombres del Conector obtiene un token para la audiencia configurada utilizando su identidad administrada de callback.
- El espacio de nombres envía el token con el evento al endpoint webhook de la extensión.
- La autenticación integrada valida la firma, expiración, emisor y audiencia del token, y comprueba que coincida
oidcon una identidad permitida. Los tokens faltantes o inválidos reciben HTTP 401; los tokens válidos de una identidad no incluida en la lista de permitidos reciben HTTP 403. - Solo las solicitudes autorizadas llegan al proveedor de funciones. Con la comprobación redundante de clave del sistema desactivada, la extensión invoca la función de destino y vincula el cuerpo del evento a su parámetro.
Tu función no necesita código de aplicación para realizar estas comprobaciones de acceso.
Documentación de autenticación relacionada
- Autenticación y autorización en Azure App Service y Azure Functions
- Configuración de una aplicación de App Service o Azure Functions para usar el inicio de sesión de Microsoft Entra
- Configuración basada en archivos en la autenticación de Servicio de aplicaciones
- Federación de identidades de carga de trabajo en Microsoft Entra ID
- Identidades administradas para recursos de Azure
Uso de Webhook
El Espacio de Nombres del Conector envía eventos al punto final del webhook de la extensión, donde el functionName valor de la cadena de consulta selecciona la función. La extensión vincula el cuerpo del evento a tu parámetro de función; no implementas un controlador HTTP.
El nombre de la función debe coincidir con el nombre de tu [Function] atributo. Las devoluciones de llamada pueden incluir x-ms-* encabezados que identifican la configuración del disparador, la conexión, el tipo de evento y el ID de correlación, pero estos encabezados no están disponibles para tu función a través del Conector Trigger.
Úsase [ConnectorTrigger] sin propiedades de sondeo. Webhook es el valor predeterminado cuando omites DeliveryMode. Consulta los ejemplos de webhooks.
Tu función puede recibir la carga útil de eventos usando cualquiera de los tipos de enlace .NET compatibles.
La extensión acepta HTTP POST y PUT solicitudes con el tipo de application/json contenido. Un cuerpo de solicitud no vacío debe contener JSON válido. Las solicitudes están sujetas al límite de cuerpo de solicitud del host de Functions y al límite de servicio ascendente; la extensión no impone un límite de tamaño de carga útil separado.
Para configurar el límite de cuerpo de solicitud del host, configure la configuración de la aplicación en FUNCTIONS_REQUEST_BODY_SIZE_LIMIT bytes y reinicie el host. Esto no es una host.json configuración y no cambia las descargas de salida vinculada de Poll, que usan extensions.connector.maxLinkedOutputSizeInBytes. Los límites más altos no garantizan los tamaños de carga útil soportados; ten en cuenta el almacenamiento en búfer, la memoria de trabajo y los límites ascendentes.
Uso de Webhook
El ayudante genérico recibe un ConnectorTriggerContext<T>. Su payload propiedad contiene el sobre de callback normalizado, items contiene los elementos del evento y rawPayload preserva la entrada analizada antes de la normalización. Los registros específicos de conectores proporcionan matrices nombradas, como emails, records, o messages.
Cada invocación gestiona una callback, que puede contener múltiples elementos de carga útil. Para una operación sin un registro específico de conector, el tipo de elemento TypeScript se unknownconfigura por defecto en . Valida la carga útil antes de acceder a propiedades específicas de la operación. Para registros tipados compatibles, consulte la referencia de extensión de conectorNode.js.
Uso de Webhook
El disparador puede vincular el cuerpo de la solicitud a str, dict, o bytes. Cuando azurefunctions-extensions-connectors registra un convertidor para la anotación del SDK de la función, el worker en su lugar desserializa el cuerpo de la solicitud en el tipo específico de operación soportado.
Cada invocación gestiona una llamada de retorno. Las ligaduras SDK compatibles proporcionan sus elementos de carga útil como una lista; utilice una anotación como list[office365.GraphClientReceiveMessage]. Para las anotaciones específicas de operación compatibles, consulte el mapeo de firmas de operación.
La extensión acepta HTTP POST y PUT solicitudes con el tipo de application/json contenido. Un cuerpo de solicitud no vacío debe contener JSON válido. Las solicitudes están sujetas al límite de cuerpo de solicitud del host de Functions y al límite de servicio ascendente.
Metadata
Actualmente, el disparador Connector no expone cabeceras de callback ni otros metadatos de solicitudes como datos vinculados. La extensión define un contrato de enlace vacío, por lo que la función solo recibe el cuerpo de la solicitud JSON en un tipo de enlace soportado por el lenguaje seleccionado.