Extensão do conector para Azure Functions visão geral (Prévia)

A extensão Connector fornece a vinculação de gatilho de entrada que executa uma função quando ocorre um evento em um serviço conectado por meio de um conector gerenciado. Para chamar operações e realizar ações nesses serviços conectados a partir do seu código de função, use um SDK Azure Connectors, que está atualmente disponível para .NET, Node.jse Python. Para mais informações sobre triggers, ações do SDK e quando usar conectores gerenciados, veja Usar conectores gerenciados no Azure Functions.

Como funciona a extensão

Uma função acionada por conector utiliza os seguintes componentes:

Quando ocorre um evento configurado, o Espaço de Nomes do Conector envia o evento para o ponto final do webhook da extensão. A extensão usa o functionName valor da sequência de consulta para selecionar a função e passa o corpo do evento JSON para o parâmetro de gatilho. O host Functions valida a chave do sistema antes que a extensão processe a solicitação, a menos que você configure outra camada de autenticação conforme descrito nos callbacks Authenticate.

Em uma função trabalhadora isolada .NET, aplique [ConnectorTrigger] ao parâmetro que recebe o corpo do evento.

Instalar a extensão

O gatilho Connector suporta o modelo de trabalhador isolado .NET. Para informações sobre versões suportadas de .NET em versões de runtime do Azure Functions, veja Linguagens por versão de runtime.

Adicione o pacote de extensão Preview Connector ao seu projeto:

dotnet add package Microsoft.Azure.Functions.Worker.Extensions.Connector --prerelease

Para usar modelos de carga útil fortemente tipados ou chamadas de operações gerenciadas de conectores, adicione também o SDK Azure Connectors de pré-visualização:

dotnet add package Azure.Connectors.Sdk --prerelease

Para versões atuais de pacotes e projetos completos, veja os exemplos de conectores Azure Functions para .NET.

Instalar a extensão

Instale os pacotes usados pelo gatilho Connector:

npm install @azure/functions @azure/functions-extensions-connectors @azure/connectors

Esses pacotes oferecem a seguinte funcionalidade:

• @azure/functions fornece o registro base connectorTrigger , que recebe a entrada do gatilho como um tipo genérico que por padrão é unknown.
• @azure/functions-extensions-connectors envolve a entrada em um contexto de gatilho de conector normalizado e fornece contextos tipados para operações de conector suportadas.
• @azure/connectors, o SDK de pré-visualização Azure Connectors para Node.js, fornece os modelos de payload usados por esses contextos e clientes para chamadas de operações de conectores.

Configure seu app para usar a versão 4.42.0 ou posterior do pacote de extensão de pré-visualização no arquivohost.json :

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.42.*, 5.0.0)"
  }
}

Para versões atuais de pacotes e projetos completos, veja os exemplos de conectores do Azure Functions para TypeScript.

Instalar a extensão

Use o modelo de programação Python v2 e instale os pacotes exigidos pelo gatilho do Connector:

azure-functions>=2.2.0
azurefunctions-extensions-connectors

A biblioteca principal de Python Azure-functions pode vincular a carga útil do gatilho a str, dict, ou bytes. O pacote azurefunctions-extensions-connectors integra o Azure Connectors SDK para Python e registra conversores adicionais para as anotações específicas do SDK operacional que ele suporta.

Configure seu app para usar a versão 4.42.0 ou posterior do pacote de extensão de pré-visualização no arquivohost.json :

{
  "version": "2.0",
  "extensionBundle": {
    "id": "Microsoft.Azure.Functions.ExtensionBundle.Preview",
    "version": "[4.42.*, 5.0.0)"
  }
}

Para versões atuais de pacotes e projetos completos, veja os exemplos de conectores Azure Functions para Python.

Tipos de associação

O gatilho Connector suporta estes tipos de parâmetros para funções de trabalho isoladas em .NET:

Para exemplos de código e comportamento específico de cargas úteis de operação, veja a referência de gatilho do Conector.

Para determinar quais operações de conector possuem modelos de payload .NET fortemente tipados, veja Operations to Azure Functions signature mapeping.

Tipos de associação

O registro base connectorTrigger passa a entrada do gatilho para um tipo genérico de handler que por padrão é unknown. O @azure/functions-extensions-connectors pacote analisa a entrada bruta em a ConnectorTriggerContext<T> com as propriedades normalizadas payload e items de , o original rawPayload, e os contextos tipados específicos da operação quando disponíveis. Para operações sem registro tipado, use o contexto genérico e valide a unknown carga útil antes de acessar seu conteúdo.

Para determinar quais operações de conector têm modelos de payload TypeScript fortemente tipados, veja Mapeamento de assinatura Operations to Azure Functions.

Tipos de associação

O gatilho Connector suporta estes tipos de parâmetros em Python:

Para determinar quais operações de conector possuem um conversor Python tiposo registrado e se a anotação representa um item ou uma coleção, veja Operations to Azure Functions signature mapeping. Use str, dict, ou bytes para operações que não possuem uma anotação de SDK suportada.

Configurar recursos do conector

Antes que a extensão possa receber um evento, crie estes recursos e configurações:

1. Um espaço de nomes de conector.
2. Uma conexão gerenciada de conector autorizada para acessar o serviço externo.
3. Uma configuração de gatilho que seleciona o evento do conector e identifica a função de destino.

A configuração do gatilho inclui a conexão gerenciada do conector, nome da operação, parâmetros da operação, URL de retorno de chamada e autenticação de retorno. Para os valores de configuração e instruções para criar um gatilho usando o CLI do Azure ou o portal do Espaço de Nomes do Conector, veja Configurar o gatilho.

Autenticar callbacks

Por padrão, a extensão Connector cria uma chave de sistema de aplicativo de função chamada connector_extension. Recupere a chave executando:

az functionapp keys list \
    --resource-group <RESOURCE_GROUP> \
    --name <FUNCTION_APP_NAME> \
    --query "systemKeys.connector_extension" \
    --output tsv

Configure a URL de retorno de chamada sem a chave:

https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>

Armazene a chave separadamente em notificationDetails.authentication:

{
  "notificationDetails": {
    "callbackUrl": "https://<FUNCTION_APP_HOSTNAME>/runtime/webhooks/connector?functionName=<FUNCTION_NAME>",
    "authentication": {
      "type": "QueryString",
      "name": "code",
      "value": "<CONNECTOR_EXTENSION_KEY>"
    }
  }
}

No momento do callback, o Espaço de Nomes do Conector adiciona a chave como o code parâmetro da sequência de consulta. Manter a chave separada da URL de retorno salva permite que o portal a mascarasse como um segredo.

Para implantações que exigem autenticação de callback baseada em identidade, use a autenticação integrada do App Service com uma identidade gerenciada em vez de uma chave de sistema compartilhada. Para o padrão completo, veja Autenticar suas funções em um namespace de conector.

configurações de host.json

A autenticação padrão por chave de sistema não exige configurações específicas de conector no arquivohost.json .

Quando a autenticação integrada do App Service valida callbacks do namespace do conector, você pode desativar a verificação redundante da chave do sistema:

{
  "version": "2.0",
  "extensions": {
    "connector": {
      "system": {
        "webhookAuthorizationLevel": "Anonymous"
      }
    }
  }
}

Use Anonymous apenas quando outra camada de autenticação, como a autenticação integrada do App Service, validar as solicitações antes que cheguem ao host das Funções.

Para uma implementação completa dessa configuração de aplicativo independente da linguagem, veja o exemplo de autenticação embutida.

Próximas Etapas 

• Managed connector trigger for Azure Function
• Use conectores gerenciados no Azure Functions
• Exemplos de conectores Azure Functions
• O que é o namespace do conector Azure?
• Referência de conectores