Guia do programador das Funções do Azure

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

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

Projeto de código

No núcleo do Azure Functions está um projeto de código específico da linguagem que implementa uma ou mais unidades de execução de código chamadas funções. As funções são simplesmente métodos que são executados na nuvem do Azure com base em eventos, em resposta a solicitações HTTP ou em uma agenda. Pense em seu projeto de código do Azure Functions como um mecanismo para organizar, implantar e gerenciar coletivamente suas funções individuais no projeto quando elas estiverem sendo executadas 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 obter mais informações, veja Conceitos de acionadores e enlaces das Funções do Azure.

O Azure Functions fornece um conjunto de modelos de projeto e função específicos da linguagem que facilitam a criação de novos projetos de código e a adição de funções ao seu projeto. Você pode usar qualquer uma das ferramentas que dão suporte ao desenvolvimento do Azure Functions para gerar novos aplicativos e funções usando esses modelos.

Ferramentas de programação

As ferramentas a seguir fornecem uma experiência integrada de desenvolvimento e publicação para o Azure Functions em seu idioma preferido:

• Visual Studio Code

• Ferramentas Principais do Azure Functions (prompt de comando)

Essas ferramentas se integram às Ferramentas Principais do Azure Functions para que você possa executar e depurar em seu computador local usando o tempo de execução do Functions. Para obter mais informações, consulte Codificar e testar o Azure Functions localmente.

Implementação

Quando você publica seu projeto de código no Azure, você está essencialmente implantando seu projeto em um recurso de aplicativo de função existente. Um aplicativo de função fornece um contexto de execução no Azure no qual suas funções são executadas. Como tal, é a unidade de implementação e gestão para as suas funções. Do ponto de vista do recurso do Azure, um aplicativo de função é equivalente a um recurso de site (Microsoft.Web/sites) no Serviço de Aplicativo do Azure, que é equivalente a um aplicativo 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 o aplicativo de função e quaisquer outros recursos necessários ainda não existem no Azure, você primeiro precisa criar esses recursos antes de implantar seus arquivos de projeto. Você pode criar esses recursos de uma destas maneiras:

• Usando o Visual Studio Code

• Usando programaticamente o Azure CLI, Azure PowerShell, modelos ARM ou modelos Bicep

• No portal do 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 obter mais informações, consulte Tecnologias de implantação no 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 associações 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 obter mais informações, veja Conceitos de acionadores e enlaces das Funções do Azure.

Se você estiver tendo problemas com erros provenientes de associações, consulte a documentação de Códigos de erro de vinculação do Azure Functions.

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 prática recomendada de segurança, o Azure Functions aproveita a funcionalidade de configurações de aplicativo do Serviço de Aplicativo do Azure para ajudá-lo a armazenar cadeias de caracteres, chaves e outros tokens necessários para se conectar a outros serviços com mais segurança. As configurações do aplicativo no Azure são armazenadas criptografadas e podem ser acessadas em tempo de execução pelo seu aplicativo como pares de variáveis name value de ambiente. Para gatilhos e associações que exigem uma propriedade de conexão, defina o nome da configuração do aplicativo em vez da cadeia de conexão real. Não é possível configurar uma associação diretamente com uma cadeia de conexão ou chave.

Por exemplo, considere uma definição de gatilho que tenha uma connection propriedade. Em vez da cadeia de conexão, você define connection como o nome de uma variável de ambiente que contém a cadeia de conexão. 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. Essas variáveis são definidas nas configurações do aplicativo ao serem executadas no Azure e no arquivo de configurações locais ao desenvolver localmente.

Valores de conexão

Quando o nome da conexão é resolvido para um único valor exato, o tempo de execução identifica o valor como uma cadeia de conexão, que normalmente inclui um segredo. Os detalhes de uma cadeia de conexão dependem do serviço ao qual você se conecta.

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 para uma definição de gatilho connection de Blob do Azure 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 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, mesmo que o serviço ao qual você está se conectando ofereça suporte a conexõ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.

Os seguintes componentes suportam conexões baseadas em identidade:

Quando hospedadas no serviço Azure Functions, as conexões baseadas em identidade usam uma identidade gerenciada. 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 do Azure, isso significa que você precisa atribuir uma função no RBAC do Azure, usando funções internas ou personalizadas que fornecem 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 conexão baseada em identidade para um serviço do Azure aceita as seguintes propriedades comuns, onde <CONNECTION_NAME_PREFIX> é o valor de sua connection propriedade na definição de gatilho ou associaçã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.

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 de usuário atual no Visual Studio
• O contexto de usuário atual no Visual Studio Code
• O contexto de usuário atual na CLI do Azure

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

Sua identidade pode já ter algumas atribuições de função em relação aos 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. 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 Segredo do cliente para uma entidade de serviço do Microsoft Entra. Essa opção de configuração não é suportada quando hospedada 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 de local.settings.json propriedades necessárias para conexão baseada em identidade com 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>"
  }
}

Conectando-se ao armazenamento do host com uma identidade

O host do Azure Functions usa a conexão de armazenamento definida AzureWebJobsStorage para habilitar comportamentos principais, como coordenar a execução singleton de gatilhos de timer e o armazenamento de chave de aplicativo padrão. 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 você estiver configurando AzureWebJobsStorage usando uma conta de armazenamento que usa o sufixo DNS padrão e o nome de serviço para o Azure global, seguindo o https://<accountName>.[blob|queue|file|table].core.windows.net formato, você pode, em vez disso, definir AzureWebJobsStorage__accountName como o nome da sua 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ê precisará criar uma atribuição de função que forneça acesso à conta de armazenamento para "AzureWebJobsStorage" em tempo de execução. Funções de gestão 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ê pode precisar de permissões adicionais se usar "AzureWebJobsStorage" para quaisquer outros fins.

Comunicar problemas

Repositórios de código aberto

O código do Azure Functions é de código aberto e você pode encontrar componentes-chave nesses repositórios do GitHub:

• Funções do Azure

• Host do Azure Functions

• Portal do Azure Functions

• Modelos do Azure Functions

• Azure WebJobs SDK (SDK de WebJobs do Azure)

• Azure WebJobs SDK Extensions (Extensões do SDK de WebJobs do Azure)

Próximos passos

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

• Cenários do Azure Functions
• Criar código e testar as Funções do Azure localmente
• Best Practices for Azure Functions (Melhores Práticas para as Funções do Azure)