Azure Functions developer guide

No Azure Functions, todas as funções partilham alguns conceitos técnicos e componentes essenciais, independentemente da sua linguagem ou ambiente de desenvolvimento preferido. Este artigo é específico do idioma. Escolha o seu idioma preferido no topo do artigo.

Este artigo parte do princípio de que já leu a visão geral Azure Functions.

Projeto de código

No cerne de Azure Functions está um projeto de código específico de uma linguagem que implementa uma ou mais unidades de execução de código chamadas functions. As funções são simplesmente métodos que correm na cloud do Azure com base em eventos, em resposta a pedidos HTTP ou num agendamento. Pense no seu projeto de código Azure Functions como um mecanismo para organizar, implementar e gerir coletivamente as suas funções individuais no projeto quando estão a correr no Azure. Para obter mais informações, consulte Organizar suas funções.

Todas as funções devem ter um gatilho, que define como a função é iniciada e pode fornecer entrada para a função. Suas funções podem, opcionalmente, definir ligações de entrada e saída. Essas associações simplificam as conexões com outros serviços sem que você precise trabalhar com SDKs de cliente. Para mais informações, veja Azure Functions gatilhos e conceitos de ligações.

O Azure Functions disponibiliza um conjunto de modelos de projetos e funções específicos para cada linguagem que facilitam a criação de novos projetos de código e a adição de funções ao seu projeto. Pode usar qualquer uma das ferramentas que suportam o desenvolvimento do Azure Functions para gerar novas aplicações e funções usando estes modelos.

Ferramentas de programação

As seguintes ferramentas proporcionam uma experiência integrada de desenvolvimento e publicação para Azure Functions na sua linguagem preferida:

• Visual Studio Code

• Azure Functions Core Tools (prompt de comandos)

Estas ferramentas integram-se com Azure Functions Core Tools para que possas executar e depurar no teu computador local usando o runtime Functions. Para mais informações, consulte Code e teste Azure Functions localmente.

Implementação

Quando publicas o teu projeto de código no Azure, estás essencialmente a implantar o teu projeto num recurso de aplicação de funções já existente. Uma aplicação de funções fornece um contexto de execução no Azure onde as suas funções correm. Como tal, é a unidade de implementação e gestão para as suas funções. De uma perspetiva Azure de recursos, uma aplicação de funções é equivalente a um recurso de site (Microsoft.Web/sites) em Azure App Service, que é equivalente a uma aplicação web.

Um aplicativo de função é composto por uma ou mais funções individuais que são gerenciadas, implantadas e dimensionadas juntas. Todas as funções em um aplicativo de função compartilham o mesmo plano de preços, método de implantação e versão de tempo de execução. Para obter mais informações, consulte Como gerenciar um aplicativo de função.

Quando a function app e quaisquer outros recursos necessários ainda não existem no Azure, primeiro precisas de criar esses recursos antes de poderes implementar os ficheiros do teu projeto. Você pode criar esses recursos de uma destas maneiras:

• Usar Visual Studio Code

• Programáticamente usando Azure CLI, Azure PowerShell, ARM ou ficheiros Bicep

• No portal Azure

Além da publicação baseada em ferramentas, o Functions suporta outras tecnologias para implantar código-fonte em um aplicativo de função existente. Para mais informações, consulte Tecnologias de implementação em Azure Functions.

Ligar aos serviços

Um dos principais requisitos de qualquer serviço de computação baseado em nuvem é ler e gravar dados em outros serviços de nuvem. O Functions fornece um extenso conjunto de associações que facilita a conexão com serviços sem precisar trabalhar com SDKs de cliente.

Se você usa as extensões de associação fornecidas pelo Functions ou trabalha diretamente com SDKs de cliente, armazena dados de conexão com segurança e não os inclui em seu código. Para obter mais informações, consulte Conexões.

Enlaces

O Functions fornece bindings para muitos serviços do Azure e alguns serviços de terceiros, que são implementados como extensões. Para obter mais informações, consulte a lista completa de associações suportadas.

As extensões de vinculação podem suportar entradas e saídas, e muitos gatilhos também atuam como ligações de entrada. As ligações permitem configurar a conexão com serviços para que o host do Functions possa lidar com o acesso aos dados para você. Para mais informações, veja Azure Functions gatilhos e conceitos de ligações.

Se estiver a ter problemas com erros provenientes de bindings, consulte a documentação de códigos de erro Azure Functions Binding Errors.

SDKs do Cliente

Embora o Functions forneça associações para simplificar o acesso a dados em seu código de função, você ainda pode usar um SDK de cliente em seu projeto para acessar diretamente um determinado serviço, se preferir. Talvez seja necessário usar SDKs de cliente diretamente caso suas funções exijam uma funcionalidade do SDK subjacente que não seja suportada pela extensão de vinculação.

Ao usar SDKs de cliente, você deve usar o mesmo processo para armazenar e acessar cadeias de conexão usadas por extensões de ligação.

Ligações

Como melhor prática de segurança, o Azure Functions aproveita a funcionalidade de definições de aplicação do Azure App Service para o ajudar a armazenar strings, chaves e outros tokens necessários para se ligar a outros serviços. As definições da aplicação em Azure são armazenadas encriptadas e podem ser acedidas em tempo de execução pela sua aplicação como pares de variáveis de ambiente namevalue. Para triggers e bindings que requerem uma propriedade de ligação, defines o nome da definição da aplicação em vez da connection string real. Não podes configurar uma ligação diretamente com uma connection string ou key.

Por exemplo, considere uma definição de gatilho que tenha uma connection propriedade. Em vez do connection string, defines connection como nome de uma variável de ambiente que contém o connection string. O uso dessa estratégia de acesso a segredos torna seus aplicativos mais seguros e facilita a alteração de conexões entre ambientes. Para ainda mais segurança, você pode usar conexões baseadas em identidade.

O provedor de configuração padrão usa variáveis de ambiente. Estas variáveis são definidas em definições de aplicação quando executadas no Azure e no ficheiro definições locais ao desenvolver localmente.

Valores de conexão

Quando o nome da ligação resolve para um único valor exato, o runtime identifica o valor como connection string, que normalmente inclui um segredo. Os detalhes de uma connection string dependem do serviço ao qual se liga.

No entanto, um nome de conexão também pode se referir a uma coleção de vários itens de configuração, úteis para configurar conexões baseadas em identidade. As variáveis de ambiente podem ser tratadas como uma coleção usando um prefixo compartilhado que termina em sublinhados __duplos. O grupo pode então ser referenciado definindo o nome da conexão para esse prefixo.

Por exemplo, a propriedade connection para uma definição de trigger de Azure Blob pode ser Storage1. Contanto que não haja um único valor de cadeia de caracteres configurado por uma variável de ambiente chamada Storage1, uma variável de ambiente nomeada Storage1__blobServiceUri pode ser usada para informar a blobServiceUri propriedade da conexão. As propriedades de conexão são diferentes para cada serviço. Consulte a documentação do componente que usa a conexão.

Configurar uma conexão baseada em identidade

Algumas ligações no Azure Functions podem ser configuradas para usar uma identidade em vez de um segredo. O suporte depende da versão do tempo de execução e da extensão que usa a conexão. Em alguns casos, uma connection string pode ainda ser necessária em Functions, mesmo que o serviço ao qual se está a ligar suporte ligações baseadas em identidade. Para obter um tutorial sobre como configurar seus aplicativos de função com identidades gerenciadas, consulte o tutorial de criação de um aplicativo de função com conexões baseadas em identidade.

Conexões baseadas em identidade são suportadas apenas no Functions 4.x, Se você estiver usando a versão 1.x, você deve primeiro migrar para a versão 4.x.

Os seguintes componentes suportam conexões baseadas em identidade:

Quando alojadas no serviço Azure Functions, as ligações baseadas em identidade utilizam uma identidade gerida. A identidade atribuída ao sistema é usada por padrão, embora uma identidade atribuída ao usuário possa ser especificada com as credential propriedades e clientID . Observe que não há suporte para a configuração de uma identidade atribuída pelo usuário com uma ID de recurso. Quando executado em outros contextos, como desenvolvimento local, sua identidade de desenvolvedor é usada, embora isso possa ser personalizado. Consulte Desenvolvimento local com conexões baseadas em identidade.

Conceder permissão à identidade

Qualquer identidade que esteja sendo usada deve ter permissões para executar as ações pretendidas. Para a maioria dos serviços Azure, isto significa que precisa de atribuir um papel no Azure RBAC, usando papéis incorporados ou personalizados que forneçam essas permissões.

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

Propriedades comuns para conexões baseadas em identidade

Uma ligação baseada em identidade para um serviço Azure aceita as seguintes propriedades comuns, onde <CONNECTION_NAME_PREFIX> é o valor da sua propriedade connection na definição de gatilho ou ligação:

Outras opções podem ser suportadas para um determinado tipo de conexão. Consulte a documentação do componente que faz a conexão.

Azure SDK Environment Variables

As variáveis de ambiente associadas ao EnvironmentCredential do Azure SDK também podem ser definidas, mas estas não são processadas pelo serviço Functions para escalabilidade nos planos de Consumo. Essas variáveis de ambiente não são específicas de nenhuma conexão e serão aplicadas como padrão, a menos que uma propriedade correspondente não seja definida para uma determinada conexão. Por exemplo, se AZURE_CLIENT_ID estiver definido, isso será usado como se <CONNECTION_NAME_PREFIX>__clientId tivesse sido configurado. A configuração <CONNECTION_NAME_PREFIX>__clientId explícita substituiria esse padrão.

Desenvolvimento local com conexões baseadas em identidade

Quando você estiver executando seu projeto de função localmente, a configuração acima informa ao tempo de execução para usar sua identidade de desenvolvedor local. A conexão tenta obter um token dos seguintes locais, na ordem:

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

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

A sua identidade pode já ter algumas atribuições de funções contra recursos do Azure usados para desenvolvimento, mas essas funções podem não fornecer o acesso necessário aos dados. Funções de gerenciamento como Proprietário não são suficientes. Verifique novamente quais permissões são necessárias para conexões para cada componente e certifique-se de atribuí-las a si mesmo.

Em alguns casos, você pode querer especificar o uso de uma identidade diferente. Pode adicionar propriedades de configuração para a ligação que apontam para a identidade alternativa com base num ID do cliente e no Secret do cliente para um principal de serviço Microsoft Entra. Esta opção de configuração não é suportada quando alojada no serviço Azure Functions. Para usar um ID e um segredo em sua máquina local, defina a conexão com as seguintes propriedades extras:

Aqui está um exemplo das propriedades local.settings.json necessárias para a ligação baseada em identidade a Azure Blobs:

{
  "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>"
  }
}

Conectando-se ao armazenamento do host com uma identidade

O Azure Functions host utiliza a ligação de armazenamento definida em AzureWebJobsStorage para ativar comportamentos essenciais, como coordenar a execução singleton dos gatilhos do temporizador e o armazenamento de chaves de aplicação por defeito. Essa conexão também pode ser configurada para usar uma identidade.

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

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

Se estiveres a configurar AzureWebJobsStorage usando uma conta de armazenamento que usa o sufixo DNS predefinido e o nome do serviço para Azure global, seguindo o formato https://<accountName>.[blob|queue|file|table].core.windows.net, podes definir AzureWebJobsStorage__accountName para o nome da tua conta de armazenamento. Os pontos de extremidade para cada serviço de armazenamento são inferidos para essa conta. Isso não funciona quando a conta de armazenamento está em uma nuvem soberana ou tem um DNS personalizado.

Você precisa criar uma atribuição de função que forneça acesso à conta de armazenamento para "AzureWebJobsStorage" em tempo de execução. Funções de gerenciamento como Proprietário não são suficientes. A função Storage Blob Data Owner cobre as necessidades básicas do armazenamento de host do Functions - o tempo de execução precisa de acesso de leitura e gravação a blobs e a capacidade de criar contêineres. Várias extensões usam essa conexão como um local padrão para blobs, filas e tabelas, e esses usos podem adicionar requisitos, conforme observado na tabela abaixo. Você também pode precisar de outras permissões se usar "AzureWebJobsStorage" para quaisquer outros fins.

¹ Para alguns tipos de problemas, Azure Functions pode gerar um evento de diagnóstico que ajuda na resolução de problemas, mesmo quando o problema impede a aplicação de funcionar de arrancar. Se o Colaborador de Dados da Tabela de Armazenamento não estiver atribuído, poderás ver avisos nos teus registos sobre a incapacidade de gravar esses eventos.

Ligar a um recurso noutro tenant

Se a tua função precisar de se ligar a um recurso num tenant Microsoft Entra diferente, a tua ligação precisa de usar uma credencial de identidade federated. Isto requer uma identidade gerida atribuída pelo utilizador e um registo da aplicação Entra ID multiinquilino. Não pode usar uma identidade gerida atribuída pelo sistema para ligações entre inquilinos.

Para configurar uma ligação baseada em identidade entre inquilinos, primeiro precisa de configurar a sua infraestrutura seguindo os seguintes passos:

1. No tenant onde a sua aplicação de funções está implementada, crie uma nova identidade gerida atribuída pelo utilizador.
2. Atribui essa identidade à aplicação de funções.
3. No mesmo inquilino, crie um registo multitenant na aplicação Entra que represente o recurso interlocatário que pretende aceder.
4. Adicione a identidade gerida como credencial de identidade federada para o registo da aplicação.
5. No tenant onde o recurso é implementado, crie uma aplicação empresarial para o registo da aplicação.
6. Atribuir permissões à aplicação empresarial para aceder ao recurso.

Uma conexão com base em identidade entre locatários utiliza as seguintes propriedades, onde <CONNECTION_NAME_PREFIX> é o valor da sua propriedade connection na definição de gatilho ou vinculação:

¹ Quando credential está definido como managedidentityasfederatedidentity, a sua ligação deve especificar exatamente um de managedIdentityClientId, managedIdentityObjectId, ou managedIdentityResourceId.

Isto é também documentado pelo Azure SDK em formato JSON.

Comunicar problemas

Repositórios de código aberto

O código do Azure Functions é open source, e pode encontrar componentes-chave nestes repositórios do GitHub:

• Azure Functions

• Azure Functions anfitrião

• Azure Functions templates

• Azure WebJobs SDK

• Azure Extensões do SDK WebJobs

Próximos passos

Para obter mais informações, consulte os seguintes recursos:

• Azure Functions cenários
• Code e teste Azure Functions localmente
• Melhores Práticas para Azure Functions