Crie a sua primeira função durável no TypeScript

Artigo
12/09/2023

Durable Functions são uma extensão do Azure Functions que permitem que você escreva funções com estado em um ambiente sem servidor. A extensão gerencia estado, pontos de verificação e reinicializações para você.

Neste artigo, você aprenderá a usar a extensão do Azure Functions do Visual Studio Code para criar e testar localmente uma função durável "hello world". Essa função orquestrará e encadeará chamadas para outras funções. Em seguida, você publicará o código de função no Azure.

Importante

O conteúdo deste artigo é alterado com base na escolha do modelo de programação Node.js no seletor na parte superior da página. O modelo v4 normalmente está disponível e foi projetado para oferecer uma experiência mais flexível e intuitiva para desenvolvedores de JavaScript e TypeScript. Saiba mais sobre as diferenças entre v3 e v4 na guia de migração.

Captura de tela de uma janela do Edge. A janela mostra a saída de invocar uma função durável simples no Azure.

Pré-requisitos

Para concluir este tutorial:

Instale o Visual Studio Code.

Instale a extensão do VS Code do Azure Functions

Instale a extensão Azure Functions do VS Code versão 1.10.4 ou posterior.

Verifique se tem a versão mais recente do Azure Functions Core Tools.

Verifique se você tem o Azure Functions Core Tools na versão v4.0.5382 ou posterior.

As Durable Functions requerem uma conta de armazenamento do Azure. É necessária uma assinatura do Azure.

Verifique se você tem a versão 16.x+ o Node.js instalada.

Verifique se você tem a versão 18.x+ do Node.js instalada.

Verifique se você tem a extensão TypeScript v4.x+ instalada.

Caso você não tenha uma assinatura do Azure, crie uma conta gratuita do Azure antes de começar.

Criar seu projeto local

Nesta seção, você usará o Visual Studio Code para criar um projeto local do Azure Functions.

No Visual Studio Code, pressione F1 (ou Ctrl/Cmd+Shift+P) para abrir a paleta de comandos. Na paleta de comandos, pesquise e selecione Azure Functions: Create New Project....
Escolha um local em uma pasta vazia para o projeto e escolha Selecionar.

Após os prompts, forneça as seguintes informações:

Prompt	Valor	Descrição
Selecione uma linguagem de programação para o seu projeto de aplicativo de função.	TypeScript	Crie um projeto local do Node.js Functions usando o TypeScript.
Selecionar um modelo de programação JavaScript	Modelo V3	Escolha o modelo de programação V3.
Selecione uma versão	Azure Functions v4	Você verá essa opção somente quando o Core Tools ainda não estiver instalado. Nesse caso, o Core Tools é instalado na primeira vez em que você executa o aplicativo.
Selecione um modelo para a primeira função do projeto	Ignorar por enquanto
Selecione como você gostaria de abrir seu projeto	Abrir na janela atual	Reabre o VS Code na pasta selecionada.

Após os prompts, forneça as seguintes informações:

Prompt	Valor	Descrição
Selecione uma linguagem de programação para o seu projeto de aplicativo de função.	TypeScript	Crie um projeto local do Node.js Functions usando o TypeScript.
Selecionar um modelo de programação JavaScript	Modelo V4	Escolha o modelo de programação V4.
Selecione uma versão	Azure Functions v4	Você verá essa opção somente quando o Core Tools ainda não estiver instalado. Nesse caso, o Core Tools é instalado na primeira vez em que você executa o aplicativo.
Selecione um modelo para a primeira função do projeto	Ignorar por enquanto
Selecione como você gostaria de abrir seu projeto	Abrir na janela atual	Reabre o VS Code na pasta selecionada.

O Visual Studio Code instalará o Azure Functions Core Tools se necessário. Ele também cria o projeto de aplicativo de funções em uma pasta. Este projeto contém os arquivos de configuração host.json e local.settings.json.

Um arquivo package.json e um arquivo tsconfig.json também são criados na pasta raiz.

Instalar o pacote npm de Durable Functions

Para trabalhar com as Durable Functions em um aplicativo de funções Node.js, use uma biblioteca chamada durable-functions.

Para usar o modelo de programação V4, você precisa instalar a versão prévia v3.x do durable-functions.

Use o menu Exibir ou Ctrl+Shift+` para abrir um novo terminal no VS Code.

Instale o pacote npm durable-functions executando npm install durable-functions no diretório raiz do aplicativo de funções.

Instale a durable-functionsversão prévia do pacote npm executando npm install durable-functions@preview no diretório raiz do aplicativo de funções.

Criando suas funções

O aplicativo Durable Functions mais básico contém três funções:

Função de orquestrador – descreve um fluxo de trabalho que orquestra outras funções.
Função de atividade – chamada pela função de orquestrador, executa o trabalho e, opcionalmente, retorna um valor.
Função de cliente – uma Função do Azure regular que inicia uma função de orquestrador. Este exemplo usa uma função disparada por HTTP.

Função de orquestrador

Use um modelo para criar o código da função durável no projeto.

Na paleta de comandos, pesquise e selecione Azure Functions: Create Function....

Após os prompts, forneça as seguintes informações:

Prompt	Valor	Descrição
Selecione um modelo para a função	Orquestrador das Durable Functions	Crie uma orquestração das Durable Functions
Escolha um tipo de armazenamento durável.	Armazenamento do Azure (padrão)	Selecione o back-end de armazenamento usado para Durable Functions.
Forneça um nome de função	HelloOrchestrator	Nome da função durável

Você adicionou um orquestrador para coordenar as funções de atividade. Abra HelloOrchestrator/index.ts para ver a função de orquestrador. Cada chamada para context.df.callActivity invoca uma função de atividade chamada Hello.

A seguir, vamos adicionar a função de atividade Hello referenciada.

Função de atividade

Na paleta de comandos, pesquise e selecione Azure Functions: Create Function....
Após os prompts, forneça as seguintes informações:

Prompt Valor Descrição

Selecione um modelo para a função Atividade das Durable Functions Crie uma função de atividade

Forneça um nome de função Olá Nome da função de atividade

Prompt	Valor	Descrição
Selecione um modelo para a função	Atividade das Durable Functions	Crie uma função de atividade
Forneça um nome de função	Olá	Nome da função de atividade

Você adicionou a função de atividade Hello, que é invocada pelo orquestrador. Abra Hello/index.ts para ver que ele está aceitando um nome como entrada e retornando uma saudação. Uma função de atividade é onde você executa "o trabalho real" em seu fluxo de trabalho: trabalhos como fazer uma chamada de banco de dados ou executar alguma computação não determinística.

Por fim, você adicionará uma função disparada por HTTP que inicia a orquestração.

Função de cliente (iniciador de HTTP)

Na paleta de comandos, pesquise e selecione Azure Functions: Create Function....

Após os prompts, forneça as seguintes informações:

Prompt	Valor	Descrição
Selecione um modelo para a função	Iniciador de HTTP das Durable Functions	Crie uma função de iniciador de HTTP
Forneça um nome de função	DurableFunctionsHttpStart	Nome da função de atividade
Nível de autorização	Anônima	Para fins de demonstração, permita que a função seja chamada sem autenticação

Você adicionou uma função disparada por HTTP que inicia uma orquestração. Abra DurableFunctionsHttpStart/index.js para ver que ela usa client.startNew para iniciar uma nova orquestração. Em seguida, ela usa client.createCheckStatusResponse para retornar uma resposta HTTP contendo URLs que podem ser usadas para monitorar e gerenciar a nova orquestração.

Agora, você tem um aplicativo das Durable Functions que pode ser executado localmente e implantado no Azure.

Um dos benefícios do Modelo de Programação V4 é a flexibilidade de onde você escreve suas funções. No Modelo V4, você pode usar um único modelo para criar todas as três funções em um arquivo em seu projeto.

Na paleta de comandos, pesquise e selecione Azure Functions: Create Function....

Após os prompts, forneça as seguintes informações:

Prompt	Valor	Descrição
Selecione um modelo para a função	Orquestrador das Durable Functions	Crie um arquivo com uma orquestração Durable Functions, uma função de atividade e uma função de inicialização do Cliente Durável.
Escolher um tipo de armazenamento durável	Armazenamento do Azure (padrão)	Selecione o back-end de armazenamento usado para Durable Functions.
Forneça um nome de função	hello	Nome usado para suas funções duráveis

Abra src/functions/hello.ts para exibir as funções que você criou.

Você adicionou um orquestrador chamado helloOrchestrator para coordenar as funções de atividade. Cada chamada para context.df.callActivity invoca uma função de atividade chamada hello.

Você também adicionou a função de atividade hello, que é invocada pelo orquestrador. No mesmo arquivo, você pode ver que ela está tomando um nome como entrada e retornando uma saudação. Uma função de atividade é onde você executa "o trabalho real" em seu fluxo de trabalho: trabalhos como fazer uma chamada de banco de dados ou executar alguma computação não determinística.

Por último, você adicionou uma função disparada por HTTP que inicia uma orquestração. No mesmo arquivo, você pode ver que ela usa client.startNew para iniciar uma nova orquestração. Em seguida, ela usa client.createCheckStatusResponse para retornar uma resposta HTTP contendo URLs que podem ser usadas para monitorar e gerenciar a nova orquestração.

Agora, você tem um aplicativo das Durable Functions que pode ser executado localmente e implantado no Azure.

Testar a função localmente

As Ferramentas Principais do Azure Functions permitem executar um projeto do Azure Functions no seu computador de desenvolvimento local. É solicitado que você instale essas ferramentas na primeira vez em que inicia uma função no Visual Studio Code.

Para testar a função, defina um ponto de interrupção no código da função de atividade Hello (Hello/index.ts). Pressione F5 ou selecione Debug: Start Debugging na paleta de comandos para iniciar o projeto do aplicativo de funções. A saída do Core Tools é exibida no painel Terminal.

Para testar a função, defina um ponto de interrupção no código da função de atividade hello (src/functions/hello.ts). Pressione F5 ou selecione Debug: Start Debugging na paleta de comandos para iniciar o projeto do aplicativo de funções. A saída do Core Tools é exibida no painel Terminal.

Observação

Confira o Diagnóstico das Durable Functions para saber mais sobre a depuração.

As Durable Functions requerem uma conta de Armazenamento do Azure para serem executadas. Quando o VS Code solicitar que você selecione uma conta de armazenamento, escolha Selecionar conta de armazenamento.

Seguindo os prompts, forneça as seguintes informações para criar uma conta de armazenamento no Azure.

Prompt	Valor	Descrição
Selecionar uma assinatura	nome da sua assinatura	Selecionar sua assinatura do Azure
Selecione uma conta de armazenamento	Criar uma nova conta de armazenamento
Insira o nome da nova conta de armazenamento	nome exclusivo	Nome da conta de armazenamento a ser criada
Selecionar um grupo de recursos	nome exclusivo	Nome do grupo de recursos a ser criado
Selecione um local	região	Selecione uma região próxima de você

No painel Terminal, copie o ponto de extremidade de URL da sua função disparada por HTTP.

Usando o navegador ou uma ferramenta como Postman ou cURL, envie uma solicitação HTTP POST para o ponto de extremidade de URL. Substitua o último segmento pelo nome da função de orquestrador (HelloOrchestrator). A URL deve ser semelhante a http://localhost:7071/api/orchestrators/HelloOrchestrator.

Usando o navegador ou uma ferramenta como Postman ou cURL, envie uma solicitação HTTP POST para o ponto de extremidade de URL. Substitua o último segmento pelo nome da função de orquestrador (helloOrchestrator). A URL deve ser semelhante a http://localhost:7071/api/orchestrators/helloOrchestrator.

A resposta é o resultado inicial da função HTTP informando que a orquestração durável foi iniciada com êxito. A resposta ainda não é o resultado final da orquestração. A resposta inclui algumas URLs úteis. Por enquanto, vamos consultar o status da orquestração.

Copie o valor da URL para statusQueryGetUri e cole-o na barra de endereços do navegador e execute a solicitação. Como alternativa, você também pode continuar usando o Postman para emitir a solicitação GET.

A solicitação consulta a instância de orquestração do status. Você deve obter uma resposta eventual, que nos mostra que a instância foi concluída e inclui as saídas ou os resultados da função durável. Ele tem esta aparência:

{
    "name": "HelloOrchestrator",
    "instanceId": "9a528a9e926f4b46b7d3deaa134b7e8a",
    "runtimeStatus": "Completed",
    "input": null,
    "customStatus": null,
    "output": [
        "Hello Tokyo!",
        "Hello Seattle!",
        "Hello London!"
    ],
    "createdTime": "2020-03-18T21:54:49Z",
    "lastUpdatedTime": "2020-03-18T21:54:54Z"
}

{
    "name": "helloOrchestrator",
    "instanceId": "6ba3f77933b1461ea1a3828c013c9d56",
    "runtimeStatus": "Completed",
    "input": "",
    "customStatus": null,
    "output": [
        "Hello, Tokyo",
        "Hello, Seattle",
        "Hello, Cairo"
    ],
    "createdTime": "2023-02-13T23:02:21Z",
    "lastUpdatedTime": "2023-02-13T23:02:25Z"
}

Para interromper a depuração, pressione Shift+F5 no VS Code.

Após verificar se a função foi executada corretamente no computador local, é hora de publicar o projeto no Azure.

Antes de poder criar recursos do Azure ou publicar seu aplicativo, você deverá entrar no Azure.

Se você ainda não tiver entrado, escolha o ícone do Azure na barra de Atividades. Em seguida, na área Recursos, escolha Entrar no Azure….

Se você já estiver conectado e puder ver suas assinaturas existentes, vá para a próxima seção. Caso ainda não tenha uma conta do Azure, escolha Criar uma conta do Azure…. Os alunos podem escolher Criar uma Conta do Microsoft Azure for Students….
Quando solicitado no navegador, escolha sua conta do Azure e entre usando suas credenciais de conta do Azure. Se você criar uma conta, poderá se conectar depois que a conta for criada.
Após entrar com êxito, você poderá fechar a nova janela do navegador. As assinaturas que pertencem à sua conta do Azure são exibidas na barra lateral.

Criar o aplicativo de funções no Azure

Nesta seção, você criará um aplicativo de funções e os recursos relacionados na sua assinatura do Azure.

Escolha o ícone do Azure na barra de atividades. Em seguida, na área Recursos, selecione o ícone + e escolha a opção Criar Aplicativo de Funções no Azure.

Forneça as seguintes informações nos prompts:

Prompt	Seleção
Selecionar uma assinatura	Escolha a assinatura a ser usada. Você não verá esse aviso quando tiver apenas uma assinatura visível em Recursos.
Insira um nome exclusivo globalmente para o aplicativo de funções	Digite um nome que seja válido em um caminho de URL. O nome que você digitar é validado para ter certeza de que ele é exclusivo no Azure Functions.
Selecionar uma pilha de runtime	Escolha a versão da linguagem em que você está fazendo a execução localmente.
Selecione uma localização para novos recursos	Para obter um melhor desempenho, escolha uma região perto de você.

A extensão mostra o status de recursos individuais conforme eles são criados no Azure no painel Azure: Log de Atividades.

Log da criação de recursos do Azure

Quando a criação for concluída, os recursos do Azure a seguir serão criados na sua assinatura. Os recursos são nomeados com base no nome do aplicativo de funções:
- Um grupo de recursos, que é um contêiner lógico para recursos relacionados.
- Uma conta de armazenamento do Azure padrão, que mantém o estado e outras informações sobre seus projetos.
- Um aplicativo de funções, que fornece o ambiente para a execução do código de função. Um aplicativo de funções lhe permite agrupar funções como uma unidade lógica para facilitar o gerenciamento, a implantação e o compartilhamento de recursos dentro do mesmo plano de hospedagem.
- Um Plano do Serviço de Aplicativo, que define o host subjacente do aplicativo de funções.
- Uma instância do Application Insights conectada ao aplicativo de funções, que controla o uso das suas funções no aplicativo.
Uma notificação é exibida depois que seu aplicativo de funções é criado e o pacote de implantação é aplicado.

Dica

Por padrão, os recursos do Azure necessários para o aplicativo de funções são criados com base no nome do aplicativo de funções fornecido por você. Por padrão, eles também são criados no mesmo grupo de recursos com o aplicativo de funções. Se desejar personalizar os nomes desses recursos ou reutilizar os recursos existentes, você precisará publicar o projeto com opções de criação avançadas.

Implantar o projeto no Azure

Importante

A implantação em um aplicativo de funções existente sempre substitui o conteúdo do aplicativo no Azure.

Na área Recursos da atividade do Azure, localize o recurso do aplicativo de funções que você acabou de criar, clique com o botão direito do mouse no recurso e selecione Implantar no aplicativo de funções....
Quando solicitado sobre a substituição de implantações anteriores, selecione Implantar para implantar seu código de função no novo recurso do aplicativo de funções.
Após a conclusão da implantação, escolha Exibir Saída para ver a criação e os resultados da implantação, incluindo os recursos do Azure que você criou. Se você perder a notificação, selecione o ícone de sino no canto inferior direito para vê-lo novamente.

Testar sua função no Azure

Observação

Para usar o modelo de programação de nó V4, verifique se o aplicativo está em execução pelo menos na versão 4.25 do runtime do Azure Functions.

Copie a URL do gatilho de HTTP do painel Saída. A URL que chama a função disparada por HTTP deve estar neste formato: https://<functionappname>.azurewebsites.net/api/orchestrators/HelloOrchestrator

Copie a URL do gatilho de HTTP do painel Saída. A URL que chama a função disparada por HTTP deve estar neste formato: https://<functionappname>.azurewebsites.net/api/orchestrators/helloOrchestrator

Cole essa nova URL para a solicitação HTTP na barra de endereços do navegador. Ao usar o aplicativo publicado, você deve obter a mesma resposta de status como antes.

Próximas etapas

Você usou o Visual Studio Code para criar e publicar um aplicativo de funções duráveis de JavaScript.

Saiba mais sobre os padrões comuns de função durável

Crie a sua primeira função durável no TypeScript

Pré-requisitos

Criar seu projeto local

Instalar o pacote npm de Durable Functions

Criando suas funções

Função de orquestrador

Função de atividade

Função de cliente (iniciador de HTTP)

Testar a função localmente

Entrar no Azure

Criar o aplicativo de funções no Azure

Implantar o projeto no Azure

Testar sua função no Azure

Próximas etapas

Recursos adicionais