Guia do desenvolvedor do Azure Functions

No Azure Functions, funções específicas compartilham alguns componentes e conceitos técnicos, independentemente da linguagem ou da associação usada. Antes de aprender detalhes específicos de uma determinada linguagem ou binding, leia esta visão geral que se aplica a todos eles.

Este artigo pressupõe que você já tenha lido a Visão geral do Azure Functions.

Código de função

Uma função é o principal conceito no Azure Functions. Uma função contém duas partes importantes: seu código, que pode estar escrito em várias linguagens e ter alguma configuração, e o arquivo function.json. Para linguagens compiladas, o arquivo de configuração é gerado automaticamente com base nas anotações no código. Para linguagens de script, você deve fornecer seu próprio arquivo de configuração.

O arquivo function.json define o gatilho, as associações e outras definições de configuração da função. Cada função tem apenas um gatilho. O runtime usa o arquivo de configuração para determinar os eventos a serem monitorados, bem como para passar e retornar dados de uma execução da função. Veja a seguir um arquivo function.json de exemplo.

{
    "disabled":false,
    "bindings":[
        // ... bindings here
        {
            "type": "bindingType",
            "direction": "in",
            "name": "myParamName",
            // ... more depending on binding
        }
    ]
}

Para obter mais informações, consulte Gatilhos e conceitos de associações do Azure Functions.

A propriedade bindings é onde você configura gatilhos e associações. Cada binding compartilha algumas configurações comuns e outras que são específicas para um determinado tipo de binding. Todas as associações exigem as seguintes configurações:

Propriedade Valores Digite Comentários
type Nome da associação.

Por exemplo, queueTrigger.
string
direction in, out string Indica se a associação é para receber dados na função ou enviar dados a partir da função.
name Identificador de função.

Por exemplo, myQueue.
string O nome que é usado para os dados associados na função. Em C#, esse é um nome de um argumento. Em JavaScript, é a chave em uma lista de chaves/valores.

Aplicativo de funções

O aplicativo de funções fornece um contexto de execução no Azure no qual suas funções são executadas. Como tal, é a unidade de implantação e gerenciamento para as suas funções. Um aplicativo de funções é composto por uma ou mais funções individuais que são gerenciadas, implantadas e dimensionadas em conjunto. Todas as funções em um aplicativo de funções compartilham o mesmo plano de preços, método de implantação e a versão de runtime. Pense em um aplicativo de funções como uma forma de organizar e gerenciar coletivamente suas funções. Para saber mais, confira Como gerenciar um aplicativo de funções.

Observação

Todas as funções em um aplicativo de funções devem ser criadas na mesma linguagem. Em versões anteriores do Azure Functions Runtime, isso não era obrigatório.

Estrutura de pastas

O código para todas as funções em um aplicativo de funções específico está localizado em uma pasta do projeto raiz que contém um arquivo de configuração do host. O arquivo host.json contém configurações específicas de runtime, além de estar na pasta raiz do aplicativo de funções. Uma pasta bin contém pacotes e outros arquivos de biblioteca que o aplicativo de funções requer. As estruturas de pastas específicas exigidas pelo aplicativo de funções dependem da linguagem:

Na versão 2.x e posterior do runtime do Functions, todas as funções no aplicativo de funções devem compartilhar a mesma pilha de linguagem.

A estrutura de pastas acima é a estrutura padrão (e recomendada) de um aplicativo de funções. Se você quiser alterar o local do arquivo do código de uma função, modifique a seção scriptFile do arquivo scriptFile. Também recomendamos usar a implantação de pacote para implantar o projeto no aplicativo de funções no Azure. Você também pode usar ferramentas existentes, como integração contínua e implantação e Azure DevOps.

Observação

Ao implantar um pacote manualmente, implante seu arquivo host.json e pastas da função diretamente na pasta . Não inclua a pasta wwwroot nas implantações. Caso contrário, você acabará com pastas wwwroot\wwwroot.

Usar ferramentas locais e publicação

Os aplicativos de funções podem ser criados e publicados com várias ferramentas, incluindo o Visual Studio, o Visual Studio Code, o IntelliJ, o Eclipse e o Azure Functions Core Tools. Para mais informações, confira Codificar e testar o Azure Functions localmente.

Como editar funções no portal do Azure

O editor do Functions interno do portal do Azure permite que você atualize o código e o arquivo function.json diretamente em linha. Isso é recomendado apenas para pequenas alterações ou provas de conceito. A melhor prática é usar uma ferramenta de desenvolvimento local, como o VS Code.

Execução paralela

Quando vários eventos de gatilho ocorrem mais rápido do que um runtime single-threaded de função pode processar, o runtime pode invocar a função várias vezes em paralelo. Se um aplicativo de funções estiver usando o Plano de hospedagem de consumo, ele poderá escalar horizontalmente de maneira automática. Cada instância do aplicativo de funções, quer seja executada no Plano de hospedagem de consumo, quer em um Plano de hospedagem do Serviço de Aplicativo comum, pode processar invocações de função simultâneas em paralelo usando vários threads. O número máximo de invocações de função simultâneas em cada instância do aplicativo de funções varia com base no tipo de gatilho que está sendo usado, bem como nos recursos usados por outras funções no aplicativo de funções.

Controle de versão de runtime de funções

Você pode configurar a versão do runtime de Funções usando a configuração de aplicativo FUNCTIONS_EXTENSION_VERSION. Por exemplo, o valor "~3" indica que seu aplicativo de funções usará 3.x como sua versão principal. Aplicativos de funções são atualizados para cada nova versão secundária à medida que elas são lançadas. Para saber mais, incluindo como exibir a versão exata do aplicativo de funções, consulte Como direcionar versões do Azure Functions runtime.

Repositórios

O código para o Azure Functions é software livre e é armazenado em repositórios do GitHub:

Associações

Veja uma tabela de todas as associações com suporte.

Esta tabela mostra as associações que são compatíveis com as versões principais do Azure Functions Runtime:

Tipo 1.x 2.x e posterior1 Gatilho Entrada Saída
Armazenamento de Blobs
Azure Cosmos DB
SQL do Azure (versão prévia)
Dapr3
Grade de Eventos
Hubs de Evento
HTTP webhooks
Hub IoT
Kafka2
Aplicativos Móveis
Hubs de Notificação
Armazenamento de filas
RabbitMQ2
SendGrid
Barramento de Serviço
SignalR
Armazenamento de tabelas
Timer
Twilio

1 A partir de runtimes de versão 2.x e posteriores, todas as associações, exceto HTTP e Timer, precisam ser registradas. Confira Registrar as extensões de associação.

2 Não há suporte para gatilhos no plano de Consumo. Requer gatilhos controlados por runtime.

3 Com suporte apenas no Kubernetes, IoT Edge e outros modos com auto-hospedagem.

Está tendo problemas com erros provenientes de associações? Examine a documentação de códigos de erro de associação do Azure Functions.

conexões

Seu projeto de função faz referência a informações de conexão por nome a partir do provedor de configuração. Ele não aceita diretamente os detalhes da conexão, permitindo que eles sejam alterados nos ambientes. Por exemplo, uma definição de gatilho pode incluir uma propriedade connection. Isso pode se referir a uma cadeia de conexão, mas você não pode definir a cadeia de conexão diretamente em um function.json. Em vez disso, você definiria connection como o nome de uma variável de ambiente que contém a cadeia de conexão.

O provedor de configuração padrão usa variáveis de ambiente. Eles podem ser definidos por configurações de aplicativo durante a execução no serviço do Azure Functions ou no arquivo de configurações local ao desenvolver localmente.

Valores de conexão

Quando o nome da conexão é resolvido para um único valor exato, o runtime identifica o valor como uma cadeia de conexão, que normalmente inclui um segredo. Os detalhes de uma cadeia de conexão são definidos pelo serviço ao qual você deseja se conectar.

No entanto, um nome de conexão também pode se referir a uma coleção de vários itens de configuração, útil para configurar conexões baseadas em identidade. As variáveis de ambiente podem ser tratadas como uma coleção ao usar um prefixo compartilhado que termina em sublinhados duplos __. Em seguida, o grupo pode ser referenciado ao definir o nome da conexão como esse prefixo.

Por exemplo, a propriedade connection para uma definição de gatilho de Blob do Azure pode ser “Storage1”. Desde que não haja um valor de cadeia de caracteres único configurado por uma variável de ambiente denominada "Storage1", uma variável de ambiente chamada Storage1__blobServiceUri poderia ser usada para informar a propriedade blobServiceUri da conexão. As propriedades de conexão são diferentes para cada serviço. Confira a documentação para ver o componente que usa a conexão.

Configurar uma conexão baseada em identidade

Algumas conexões no Azure Functions podem ser configuradas para usar uma identidade em vez de um segredo. O suporte depende da extensão que usa a conexão. Em alguns casos, uma cadeia de conexão ainda pode ser necessária no Functions, embora o serviço ao qual você está se conectando ofereça suporte a conexões baseadas em identidade. Para ver um tutorial sobre a configuração de aplicativos de funções com identidades gerenciadas, confira o tutorial sobre como criar um aplicativo de funções com conexões baseadas em identidade.

As conexões baseadas em identidade são suportadas pelos componentes a seguir:

Fonte de conexão Planos com suporte Saiba mais
Gatilhos e associações do Blob do Azure Tudo Versão de extensão 5.0.0 ou posterior
Gatilhos e associações da Fila do Azure Tudo Versão de extensão 5.0.0 ou posterior
Gatilhos e associações dos Hubs de Eventos do Azure Tudo Versão de extensão 5.0.0 ou posterior
Gatilhos e associações do Barramento de Serviço do Azure Tudo Versão de extensão 5.0.0 ou posterior
Gatilhos e associações do Azure Cosmos DB – Versão prévia Elástico Premium Versão de extensão 4.0.0-preview1 ou posterior
Armazenamento necessário do host ("AzureWebJobsStorage") – Versão prévia Tudo Conectar-se ao armazenamento de host com uma identidade

Observação

Não há suporte para conexões baseadas em identidade com Durable Functions.

Quando hospedadas no serviço de Azure Functions, as conexões baseadas em identidade usam uma identidade gerenciada. A identidade atribuída pelo sistema é usada por padrão, embora a identidade atribuída pelo usuário possa ser especificada com as propriedades credential e clientID. Quando executado em outros contextos, como desenvolvimento local, a identidade do desenvolvedor é usada, embora isso possa ser personalizado. Confira Desenvolvimento local com conexões baseadas em identidade.

Conceder permissão para a identidade

Qualquer identidade que esteja sendo usada deve ter permissões para executar as ações pretendidas. Você precisará atribuir uma função no controle de acesso baseado em função do Azure usando funções internas ou personalizadas que forneçam essas permissões.

Importante

Algumas permissões que não são necessárias em todos os contextos podem ser expostas pelo serviço de destino. Sempre que possível, siga o princípio do privilégio mínimo, concedendo à identidade apenas os privilégios necessários. Por exemplo, se o aplicativo precisar apenas ser capaz de ler uma fonte de dados, use uma função que só tenha permissão de leitura. Seria inapropriado atribuir uma função que também permitisse a gravação nesse serviço, pois seria um excesso de permissões para uma operação de leitura. Da mesma forma, seria melhor garantir que a atribuição da função tivesse o escopo apenas sobre os recursos que precisam ser lidos.

Escolha uma das guias abaixo para saber mais sobre as permissões para cada componente:

Você precisará criar uma atribuição de função que forneça acesso ao contêiner de blobs em runtime. Funções de gerenciamento como Proprietário não são suficientes. A tabela a seguir mostra as funções internas recomendadas ao usar a extensão do Armazenamento de Blobs em operação normal. Seu aplicativo pode exigir permissões adicionais com base no código escrito por você.

Tipo de associação Exemplo de funções internas
Gatilho Proprietário de dados do blob de armazenamento e Colaborador de dados de fila de armazenamento1
Associação de entrada Leitor de Dados do Blob de Armazenamento
Associação de saída Proprietário de Dados do Blob de Armazenamento

1Por padrão, o gatilho do blob usa as Filas do Azure internamente. Portanto, isso também exige permissões de Colaborador de dados de fila de armazenamento para criar e receber mensagens.

Propriedades comuns para conexões baseadas em identidade

Uma conexão baseada em identidade para um serviço do Azure aceita as seguintes propriedades comuns, em que <CONNECTION_NAME_PREFIX> é o valor da propriedade connection no gatilho ou na definição de associação:

Propriedade Modelo de variável de ambiente Descrição
Credencial de token <CONNECTION_NAME_PREFIX>__credential Define como um token deve ser obtido para a conexão. Recomendado somente ao especificar uma identidade atribuída pelo usuário, quando deve ser definido como "managedidentity". Isso só é válido quando hospedado no serviço do Azure Functions.
ID do Cliente <CONNECTION_NAME_PREFIX>__clientId Quando credential está definida como "managedidentity", essa propriedade especifica a identidade atribuída pelo usuário a ser usada ao obter um token. A propriedade aceita uma ID de cliente correspondente a uma identidade atribuída pelo usuário atribuída ao aplicativo. Se não especificada, a identidade atribuída pelo sistema será usada. Essa propriedade é usada de maneira diferente em cenários de desenvolvimento locais, em que pode não estar definida.

Outras opções podem ter suporte para um determinado tipo de conexão. Confira a documentação do componente que está fazendo a conexão.

Desenvolvimento local com conexões baseadas em identidade

Observação

O desenvolvimento local com conexões baseadas em identidades requer versões atualizadas do Azure Functions Core Tools. Execute func -v para verificar a versão atualmente instalada. Para o Functions v3, use a versão 3.0.3904 ou posterior. Para o Functions v4, use a versão 4.0.3904 ou posterior.

Ao executar localmente, a configuração acima informa o runtime para usar sua identidade de desenvolvedor local. A conexão tentará obter um token dos seguintes locais, na ordem apresentada:

  • Um cache local compartilhado entre aplicativos da Microsoft
  • O contexto do usuário atual no Visual Studio
  • O contexto do usuário atual no Visual Studio Code
  • O contexto do usuário atual na CLI do Azure

Se nenhuma dessas opções for bem-sucedida, ocorrerá um erro.

Como isso está usando sua identidade de desenvolvedor, talvez você já tenha algumas funções em relação aos recursos de desenvolvimento, mas elas podem não fornecer acesso a dados. As funções de gerenciamento como a de Proprietário não são suficientes. Verifique duas vezes quais permissões são necessárias para as conexões para cada componente, e verifique se você as atribuiu a si mesmo.

Em alguns casos, talvez você queira especificar o uso de uma identidade diferente. Você pode adicionar propriedades de configuração para a conexão que apontam para a identidade alternativa com base em uma ID do cliente e um segredo do cliente para uma entidade de serviço do Azure Active Directory. Essa configuração não têm suporte quando hospedada no serviço do Azure Functions. Para usar uma ID e um segredo em seu computador local, defina a conexão com as seguintes propriedades adicionais:

Propriedade Modelo de variável de ambiente Descrição
ID do locatário <CONNECTION_NAME_PREFIX>__tenantId ID de locatário do Azure Active Directory (diretório).
ID do Cliente <CONNECTION_NAME_PREFIX>__clientId A ID do cliente (aplicativo) de um registro de aplicativo no locatário.
Segredo do cliente <CONNECTION_NAME_PREFIX>__clientSecret Um segredo do cliente que foi gerado para o registro do aplicativo.

Aqui está um exemplo de propriedades local.settings.json necessárias para a conexão baseada em identidade com os Blobs do Azure:

{
  "IsEncrypted": false,
  "Values": {
    "<CONNECTION_NAME_PREFIX>__blobServiceUri": "<blobServiceUri>",
    "<CONNECTION_NAME_PREFIX>__queueServiceUri": "<queueServiceUri>",
    "<CONNECTION_NAME_PREFIX>__tenantId": "<tenantId>",
    "<CONNECTION_NAME_PREFIX>__clientId": "<clientId>",
    "<CONNECTION_NAME_PREFIX>__clientSecret": "<clientSecret>"
  }
}

Conectar-se ao armazenamento de host com uma identidade (versão prévia)

O Azure Functions, por padrão, usa a conexão "AzureWebJobsStorage" para comportamentos básicos, como a coordenação de execução singleton de gatilhos de temporizador e armazenamento de chave de aplicativo padrão. Isso também pode ser configurado para aproveitar uma identidade.

Cuidado

Outros componentes no Functions dependem do "AzureWebJobsStorage" para comportamentos padrão. Você não deve movê-lo para uma conexão baseada em identidade se estiver usando versões mais antigas de extensões que não suportam esse tipo de conexão, incluindo gatilhos e associações para Blobs do Azure e para Hubs de Eventos. Da mesma forma, AzureWebJobsStorage é usado para artefatos de implantação ao usar a compilação do lado do servidor no Consumo em Linux e, se você habilitar isso, precisará implantar usando AzureWebJobsStorage.

Além disso, alguns aplicativos reutilizam o "AzureWebJobsStorage" para outras conexões de armazenamento nos gatilhos, associações e/ou códigos de função. Garanta que todos os usos do "AzureWebJobsStorage" sejam capazes de usar o formato de conexão baseado em identidade antes de alterar esta conexão de uma cadeia de conexão.

Para usar uma conexão baseada em identidade para o "AzureWebJobsStorage", defina as seguintes configurações de aplicativo:

Configuração Descrição Valor de exemplo
AzureWebJobsStorage__blobServiceUri O URI do plano de dados do serviço de blobs da conta de armazenamento, usando o esquema HTTPS. https://<storage_account_name>.blob.core.windows.net
AzureWebJobsStorage__queueServiceUri O URI do plano de dados do serviço de filas da conta de armazenamento, usando o esquema HTTPS. https://<storage_account_name>.queue.core.windows.net

As propriedades comuns para conexões baseadas em identidade também podem ser definidas.

Se você estiver usando uma conta de armazenamento que usa o sufixo DNS padrão e o nome do serviço para o Azure global seguindo o formato https://<accountName>.blob/queue/file/table.core.windows.net, é possível, ao invés disso, definir o nome da sua conta de armazenamento como AzureWebJobsStorage__accountName. Os pontos de extremidade de blob e de fila serão inferidos para essa conta. Isso não funcionará se a conta de armazenamento estiver em uma nuvem soberana ou tiver um DNS personalizado.

Configuração Descrição Valor de exemplo
AzureWebJobsStorage__accountName O nome de uma conta de armazenamento, válido somente se a conta não estiver em uma nuvem soberana e não tiver um DNS personalizado. <storage_account_name>

Será necessário criar uma atribuição de função que forneça acesso à conta de armazenamento para "AzureWebJobsStorage" no tempo de execução. Funções de gerenciamento como Proprietário não são suficientes. A função de Proprietário de Dados do Blob de Armazenamento abrange as necessidades básicas do armazenamento de host de Funções, o tempo de execução precisa de acesso de leitura e gravação aos blobs e à capacidade de criar contêineres. Há algumas situações, assim como acontece com o uso do gatilho de blob, onde o Armazenamento colaborador de dados de fila também pode ser necessário. Você poderá precisar de permissões adicionais se usar "AzureWebJobsStorage" para outras finalidades.

Problemas de relatórios

Item Descrição Link
Runtime Host de Script, Gatilhos & Associações, Suporte ao Idioma Registrar um Problema
Modelos Problemas de Código com o Modelo de Criação Registrar um Problema
Portal Interface do Usuário ou Problema de Experiência Registrar um Problema

Próximas etapas

Para saber mais, consulte os recursos a seguir: