Executar uma função do Azure em resposta a um evento de reidratação de blobs

Para ler um blob que está na camada de acesso aos arquivos, primeiro reidrate o blob para a camada de acesso frequente ou esporádico. O processo de reidratação pode levar várias horas. Em vez de sondar o status da operação de reidratação repetidamente, configure a Grade de Eventos do Azure para acionar um evento quando a operação de reidratação do blob estiver concluída e tratar esse evento no seu aplicativo.

Quando um evento ocorre, a Grade de Eventos envia o evento para um manipulador de eventos por meio de um ponto de extremidade. Vários serviços do Azure podem servir como manipuladores de eventos, incluindo o Azure Functions. Função do Azure é um bloco de código que pode ser executado em resposta a um evento. Esse tutorial explica o processo de desenvolvimento de uma função do Azure e, em seguida, a configuração da Grade de Eventos para executar a função em resposta a um evento que ocorre quando um blob é reidratado.

Este artigo mostra como criar e testar uma função do Azure com o .NET do Visual Studio. Você pode criar funções do Azure a partir de vários ambientes de desenvolvimento locais e usar uma variedade de linguagens de programação diferentes. Para mais informações sobre as linguagem com suporte para o Azure Functions, confira Linguagens com suporte no Azure Functions. Para obter mais informações sobre as opções de desenvolvimento do Azure Functions, confira Codificar e testar o Azure Functions localmente.

Para obter mais informações sobre como reidratar blobs da camada de armazenamento de arquivos, confira Visão geral da reidratação de blob da camada de arquivo morto.

Pré-requisitos

Este arquivo mostra como usar o Visual Studio 2019 ou posterior para desenvolver funções do Azure com o .NET. É possível instalar o Visual Studio Community gratuitamente. Configure o Visual Studio para o desenvolvimento do Azure com o .NET.

Para depurar a função do Azure localmente, você precisará usar uma ferramenta que possa enviar uma solicitação HTTP, como o Postman.

Será necessário ter uma assinatura do Azure. Se você ainda não tiver uma conta, crie uma gratuita antes de começar.

Criar um Aplicativo de funções do Azure

Aplicativo de funções é um recurso do Azure que serve como um contêiner para suas funções do Azure. Você pode usar um aplicativo de funções novo ou existente para concluir as etapas descritas neste artigo.

Para criar um aplicativo de funções no portal do Azure, siga estas etapas:

1. No portal do Azure, procure o Aplicativo de funções. Selecione o ícone do Aplicativo de funções para navegar para a lista de aplicativos de funções da sua assinatura.

2. Selecione o botão Criar para criar um novo aplicativo de funções.

3. Na guia Informações básicas, especifique um grupo de recursos e forneça um nome exclusivo para o novo aplicativo de funções.

4. Defina a opção Publicar como Código.

5. Na lista suspensa Pilha de runtime, selecione .NET. O campo Versão é preenchido automaticamente para usar a versão mais recente do .NET Core.

6. Selecione a região do novo aplicativo de funções.

   

7. Depois de preencher a guia Informações básicas, navegue até a guia Hospedagem.

8. Na guia Hospedagem, selecione a conta de armazenamento em que a sua função do Azure será armazenada. Escolha uma conta de armazenamento existente ou crie uma nova.

9. Defina o campo Sistema operacional como Windows.

10. No campo Tipo de plano, selecione Consumo (sem servidor) . Para obter mais informações sobre esse plano, confira Hospedagem do plano de consumo do Azure Functions.

    

11. Selecione Revisar + Criar para criar um novo aplicativo de funções.

Para saber mais sobre como configurar o aplicativo de funções, confira Gerenciar seu aplicativo de funções na documentação do Azure Functions.

Criar uma função do Azure com um gatilho da Grade de Eventos

Agora, crie uma função do Azure que será executado quando um blob for reidratado em uma conta de armazenamento específica. Siga estas etapas para criar uma função do Azure no Visual Studio com C# e .NET Core:

1. Inicialize o Visual Studio 2019 e crie um novo projeto do Azure Functions. Para obter mais detalhes, siga as instruções descritas em Criar um projeto de aplicativo de funções.

2. Na etapa Criar um novo aplicativo do Azure Functions, selecione os seguintes valores:

   • Por padrão, o runtime do Azure Functions é definido como Azure Functions v3 (.NET Core) . A Microsoft recomenda usar essa versão do runtime do Azure Functions.
   • Na lista de gatilhos possíveis, selecione Gatilho da Grade de Eventos. Para saber por quê o gatilho da Grade de Eventos é o tipo de gatilho recomendado para tratar eventos de armazenamento de Blobs com funções do Azure, confira Usar uma função do Azure como um manipulador de eventos nos eventos da Grade de Eventos.
   • A configuração da Conta de armazenamento indica onde a função do Azure será armazenada. Você pode selecionar uma conta de armazenamento existente ou criar uma nova.

3. Selecione Criar para criar um projeto no Visual Studio.

4. Agora, renomeie a classe e a função do Azure, conforme descrito em Renomear a função. Escolha um nome adequado ao seu cenário.

5. No Visual Studio, selecione Ferramentas | Gerenciador de pacotes do NuGet | Console do gerenciador de pacotes e instale os seguintes pacotes a partir do console:

   Install-Package Azure.Storage.Blobs
   Install-Package Microsoft.ApplicationInsights.WorkerService
   Install-Package Microsoft.Azure.WebJobs.Logging.ApplicationInsights
   

6. No arquivo de classe da função do Azure, cole o seguinte usando instruções:

   using System;
   using System.IO;
   using System.Text;
   using Microsoft.Azure.WebJobs;
   using Microsoft.Azure.EventGrid.Models;
   using Microsoft.Azure.WebJobs.Extensions.EventGrid;
   using Microsoft.Extensions.Logging;
   using Azure;
   using Azure.Storage.Blobs;
   using Azure.Storage.Blobs.Models;
   

7. Localize o método Run no arquivo de classe. Esse é o método executado quando ocorre um evento. Cole o código a seguir no corpo do método Run. Lembre-se de substituir os valores dos espaços reservados entre colchetes angulares pelos seus próprios valores:

   // When either Microsoft.Storage.BlobCreated or Microsoft.Storage.BlobTierChanged
   // event occurs, write the event details to a log blob in the same container
   // as the event subject (the blob for which the event occurred).
   
   // Create a unique name for the log blob.
   string logBlobName = string.Format("function-log-{0}.txt", DateTime.UtcNow.Ticks);
   
   // Populate connection string with your Shared Key credentials.
   const string ConnectionString = "DefaultEndpointsProtocol=https;AccountName=<account-name>;AccountKey=<account-key>;EndpointSuffix=core.windows.net";
   
   // Get data from the event.
   dynamic data = eventGridEvent.Data;
   string eventBlobUrl = Convert.ToString(data.url);
   string eventApi = Convert.ToString(data.api);
   
   // Build string containing log information.
   StringBuilder eventInfo = new StringBuilder();
   eventInfo.AppendLine(string.Format("{0} operation occurred.", eventApi));
   eventInfo.AppendLine(string.Format("Blob URL: {0}", eventBlobUrl));
   eventInfo.AppendLine($@"Additional event details:
       Id=[{eventGridEvent.Id}]
       EventType=[{eventGridEvent.EventType}]
       EventTime=[{eventGridEvent.EventTime}]
       Subject=[{eventGridEvent.Subject}]
       Topic=[{eventGridEvent.Topic}]");
   
   // If event was BlobCreated and API call was CopyBlob, respond to the event.
   bool copyBlobEventOccurred = (eventGridEvent.EventType == "Microsoft.Storage.BlobCreated") &&
                                (eventApi == "CopyBlob");
   
   // If event was BlobTierChanged and API call was SetBlobTier, respond to the event.
   bool setTierEventOccurred = (eventGridEvent.EventType == "Microsoft.Storage.BlobTierChanged") &&
                               (eventApi == "SetBlobTier");
   
   // If one of these two events occurred, write event info to a log blob.
   if (copyBlobEventOccurred | setTierEventOccurred)
   {
       // Create log blob in same account and container.
       BlobUriBuilder logBlobUriBuilder = new BlobUriBuilder(new Uri(eventBlobUrl))
       {
           BlobName = logBlobName
       };
   
       BlobClient logBlobClient = new BlobClient(ConnectionString,
                                                 logBlobUriBuilder.BlobContainerName,
                                                 logBlobName);
   
       byte[] byteArray = Encoding.ASCII.GetBytes(eventInfo.ToString());
   
       try
       {
           // Write the log info to the blob.
           // Overwrite if the blob already exists.
           using (MemoryStream memoryStream = new MemoryStream(byteArray))
           {
               BlobContentInfo blobContentInfo =
                   logBlobClient.Upload(memoryStream, overwrite: true);
           }
       }
       catch (RequestFailedException e)
       {
           Console.WriteLine(e.Message);
           throw;
       }
   }
   

Para obter mais informações sobre como desenvolver funções do Azure, confira Orientação para desenvolver no Azure Functions.

Para saber mais sobre as informações incluídas quando o evento do Armazenamento de Blobs é publicado em um manipulador de eventos, confira Armazenamento de Blobs do Azure como origem da Grade de Eventos.

Executar a função do Azure localmente no depurador

Para testar o código da função do Azure localmente, é necessário enviar manualmente uma solicitação HTTP que dispare o evento. Você pode postar a solicitação usando uma ferramenta como o Postman.

Na parte superior do arquivo de classe da sua função do Azure, há um ponto de extremidade de URL que você pode usar para teste no ambiente local. Postar a solicitação com essa URL dispara o evento no ambiente local para que você depure seu código. O URL está neste formato:

http://localhost:7071/runtime/webhooks/EventGrid?functionName={functionname}

A solicitação que você envia para esse ponto de extremidade é uma solicitação simulada. Ela não envia nem recebe dados de sua conta de armazenamento do Microsoft Azure.

Siga estas etapas para construir e enviar uma solicitação para esse ponto de extremidade. Este exemplo mostra como enviar a solicitação com o Postman.

1. No Postman, crie uma nova solicitação.

2. Cole o URL mostrado acima no campo do URL solicitado, substituindo o nome da sua função por {functionname} e removendo as chaves. Defina o verbo de solicitação como GET.

   

3. Adicione um cabeçalho Content-Type e defina-o como application/json.

4. Adicione o cabeçalho aeg-event-type e defina-o como Notificação.

   

5. No Postman, especifique o corpo da solicitação. O tipo de corpo deve estar definido como JSON e o formato como raw. O exemplo a seguir simula uma solicitação Copiar Blob. Substitua os valores dos espaços reservados entre colchetes angulares pelos seus valores. Observe que não é necessário alterar valores de data/hora ou identificador, pois essa é uma solicitação simulada:

   [{
     "topic": "/subscriptions/<subscription-id>/resourceGroups/<resource-group>/providers/Microsoft.Storage/storageAccounts/<storage-account>",
     "subject": "/blobServices/default/containers/<container-name>/blobs/<blob-name>",
     "eventType": "Microsoft.Storage.BlobCreated",
     "id": "2bfb587b-501e-0094-2746-8b2884065d32",
     "data": {
       "api": "CopyBlob",
       "clientRequestId": "3d4dedc7-6c27-4816-9405-fdbfa806b00c",
       "requestId": "2bfb587b-501e-0094-2746-8b2884000000",
       "eTag": "0x8D9595DCA505BDF",
       "contentType": "text/plain",
       "contentLength": 48,
       "blobType": "BlockBlob",
       "url": "https://<storage-account>.blob.core.windows.net/<container-name>/<blob-name>",
       "sequencer": "0000000000000000000000000000201B00000000004092a5",
       "storageDiagnostics": {
         "batchId": "8a92736a-6006-0026-0046-8bd7f5000000"
       }
     },
     "dataVersion": "",
     "metadataVersion": "1",
     "eventTime": "2021-08-07T04:42:41.0730463Z"
   }]
   

6. No Visual Studio, coloque todos os pontos de interrupção no seu código e pressione F5 para executar o depurador.

7. No Postman, clique no botão Enviar para enviar a solicitação para o ponto de extremidade.

Quando você envia a solicitação, a Grade de Eventos chama sua função do Azure e você pode depurá-la normalmente. Para obter mais informações e exemplos, confira Postar manualmente a solicitação na documentação do Azure Functions.

A solicitação que dispara o evento é simulada, mas a função do Azure executada quando o evento é acionado grava informações de log em um novo blob em sua conta de armazenamento. Você pode verificar o conteúdo do blob e exibir sua hora da última modificação no portal do Azure, conforme mostrado na imagem a seguir:

Como publicar a Azure Function

Depois de testar a função do Azure localmente, a próxima etapa é publicar a função do Azure no aplicativo de funções do Azure que você criou anteriormente. A função deve ser publicada para que você configure a Grade de Eventos para enviar eventos que ocorrem na conta de armazenamento para o ponto de extremidade da função.

Siga estas etapas para publicar a função:

1. No Gerenciador de Soluções, Selecione e mantenha pressionado (ou clique com o botão direito do mouse) o projeto do Azure Functions e escolha Publicar.

2. Na janela Publicar, selecione Azure como o destino e escolha Avançar.

3. Selecione Aplicativo de funções do Azure (Windows) como o destino específico e escolha Avançar.

4. Na guia Instância do Azure Functions, selecione a sua assinatura no menu suspenso e localize o seu aplicativo de funções do Azure na lista de aplicativos de funções disponíveis.

5. Marque a caixa de verificação Executar a partir do arquivo de pacote.

6. Escolha Finalizar para preparar a publicação da função.

7. Na página Publicar, verifique se a configuração está correta. Se você vir um aviso de que a dependência de serviço para o Application Insights não está configurada, configure-a nesta página.

8. Clique no botão Publicar para iniciar a publicação da função do Azure no aplicativo de funções do Azure criado antes.

   

Sempre que você fizer alterações no código em sua função do Azure, deverá publicar a função atualizada no Azure.

Assinar eventos de reidratação de blob de uma conta de armazenamento

Agora você tem um aplicativo de funções que contém uma função do Azure que pode ser executada em resposta a um evento. A próxima etapa é criar uma assinatura de evento da sua conta de armazenamento. A assinatura de evento configura a conta de armazenamento para publicar um evento por meio da Grade de Eventos em resposta a uma operação em um blob de sua conta de armazenamento. A Grade de Eventos envia o evento para o ponto de extremidade do manipulador de eventos que você especificou. Nesse caso, o manipulador de eventos é a função do Azure que você criou na seção anterior.

Ao criar a assinatura de evento, você pode filtrar quais eventos são enviados para o manipulador de eventos. Os eventos a serem capturados ao reidratar um blob da camada de acesso aos arquivos são Microsoft.Storage.BlobTierChanged, correspondente a uma operação Definir Camada do Blob, e eventos Microsoft.Storage.BlobCreated, correspondentes a uma operação Copiar Blob. Dependendo do seu cenário, você pode querer manipular apenas um desses eventos.

Para criar uma assinatura de evento, siga estas etapas:

1. Na portal do Azure, navegue até a conta de armazenamento que contém os blobs para reidratar da camada de armazenamento de arquivos.

2. Selecione as configurações de Eventos no painel de navegação esquerdo.

3. Na página Eventos, selecione Mais opções.

4. Selecione Criar uma assinatura de evento.

5. Na página Criar uma assinatura de evento, na seção Detalhes da assinatura de evento, forneça um nome para a assinatura de evento.

6. Na seção Detalhes do tópico, forneça um nome para o tópico do sistema. O tópico do sistema representa um ou mais eventos que são publicados pelo Armazenamento do Microsoft Azure. Para obter mais informações sobre os tópicos do sistema, confira Tópicos do sistema na Grade de Eventos do Azure.

7. Na seção Tipos de evento, selecione os eventos Blob Criado e Alteração da Camada de Blob. Dependendo de como você optar por reidratar um blob da camada de acesso aos arquivos, um desses dois eventos será acionado.

   

8. Na seção Detalhes dos pontos de extremidade, selecione Função do Azure no menu suspenso.

9. Escolha Selecionar um ponto de extremidade para especificar a função que você criou na seção anterior. Na caixa de diálogo Selecionar função do Azure, escolha a assinatura, o grupo de recursos e o aplicativo de funções da função do Azure. Por fim, selecione o nome da função na lista suspensa e clique em Confirmar seleção.

   

10. Selecione o botão Criar para criar a assinatura de evento e começar a enviar eventos para o manipulador de eventos da função do Azure.

Para saber mais sobre assinaturas de evento, confira Conceitos da Grade de Eventos do Azure.

Testar o manipulador de eventos da função do Azure

Para testar a função do Azure, você pode disparar um evento na conta de armazenamento que contém a assinatura de evento. A assinatura de evento que você criou antes é filtrada em dois eventos: Microsoft.Storage.BlobCreated e Microsoft.Storage.BlobTierChanged. Quando um desses eventos é acionado, ele dispara sua função do Azure.

A função do Azure mostrada neste artigo grava em um blob de log em dois cenários:

• Quando o evento é Microsoft.Storage.BlobCreated, e a operação de API é Copiar Blob.
• Quando o evento é Microsoft.Storage.BlobTierChanged, e a operação de API é Definir Camada do Blob.

Para saber como testar a função reidratando um blob, consulte um destes dois procedimentos:

• Reidratar um blob com uma operação de cópia
• Reidratar um blob alterando sua camada

Depois que a reidratação for concluída, o blob de log será gravado no mesmo contêiner do blob que você reidratou. Por exemplo, depois de reidratar um blob com uma operação de cópia, você pode ver no portal do Azure que o blob de origem permanece na camada de acesso aos arquivos, o blob de destino totalmente reidratado aparece na camada online de destino e o blob de log criado pela função do Azure também aparece na lista.

Saiba que reidratar um blob pode levar até 15 horas, dependendo da configuração de prioridade da reidratação. Se você definir a prioridade da reidratação como Alta, a reidratação poderá levar menos de uma hora se o blob tiver menos do que 10 GB. No entanto, um reidratação de alta prioridade gera um custo maior. Para obter mais informações, confira Visão geral da reidratação de blob da camada de arquivos.

Dica

Embora a meta deste tutorial seja manipular esses eventos no contexto de reidratação do blob, para fins de teste, pode ser útil observar esses eventos em resposta ao carregamento de blobs ou a alteração de uma camada de blob online (por exemplo: da camada de acesso frequente para a camada de acesso esporádico) porque o evento é acionado imediatamente.

Para obter mais informações sobre como filtrar eventos na Grade de Eventos, confira Como filtrar eventos da Grade de Eventos do Azure.

Confira também

• Camadas de acesso quente, fria e aos arquivos para dados de blob
• Visão geral da reidratação de blob da camada de arquivo morto
• Reidratar um blob arquivado em uma camada online
• Reagindo a eventos de Armazenamento de Blobs