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

  • Artigo

Para ler um blob que está na camada de arquivo, você deve primeiro reidratar o blob para a camada quente ou fria. O processo de reidratação pode levar várias horas para ser concluído. Em vez de sondar repetidamente o status da operação de reidratação, você pode configurar a Grade de Eventos do Azure para disparar um evento quando a operação de reidratação de blob estiver concluída e manipular esse evento em seu aplicativo.

Quando ocorre um evento, 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. Uma Função do Azure é um bloco de código que pode ser executado em resposta a um evento. Este tutorial orienta você pelo processo de desenvolvimento de uma Função do Azure e, em seguida, pela 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 .NET do Visual Studio. Você pode criar o Azure Functions a partir de uma variedade de ambientes de desenvolvimento local e usando uma variedade de linguagens de programação diferentes. Para obter mais informações sobre idiomas com suporte para o Azure Functions, consulte Idiomas com suporte no Azure Functions. Para obter mais informações sobre opções de desenvolvimento para o Azure Functions, consulte Codificar e testar o Azure Functions localmente.

Para obter mais informações sobre a reidratação de blobs da camada de arquivamento, consulte Visão geral da reidratação de blob da camada de arquivamento.

Pré-requisitos

Este artigo mostra como usar o Visual Studio 2019 ou posterior para desenvolver uma função do Azure com .NET. Você pode instalar o Visual Studio Community gratuitamente. Certifique-se de configurar o Visual Studio para Desenvolvimento do Azure com .NET.

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

É necessária uma subscrição do Azure. Se você ainda não tem uma conta, crie uma gratuita antes de começar.

Criar uma aplicação de Funções do Azure

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

Para criar um novo aplicativo de função no portal do Azure, siga estas etapas:

  1. No portal do Azure, procure por Function App. Selecione o ícone Aplicativo de função para navegar até a lista de aplicativos de função em sua assinatura.

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

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

  4. Certifique-se de que a opção Publicar está definida como Código.

  5. Na lista suspensa Pilha de tempo de execução, selecione .NET. O campo Versão é preenchido automaticamente para usar a versão mais recente do núcleo do .NET.

  6. Selecione a região para o novo aplicativo de função.

    Screenshot showing how to create a new function app in Azure - Basics tab

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

  8. Na guia Hospedagem, selecione a conta de armazenamento onde sua Função do Azure será armazenada. Você pode escolher uma conta de armazenamento existente ou criar uma nova.

  9. Certifique-se de que o campo Sistema operacional está definido como Windows.

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

    Screenshot showing how to create a new function app in Azure - Hosting tab

  11. Selecione Rever + Criar para criar a nova aplicação funcional.

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

Criar uma função do Azure como um gatilho de grade de eventos

Em seguida, crie uma Função do Azure que será executada 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. Inicie o Visual Studio 2019 e crie um novo projeto do Azure Functions. Para obter detalhes, siga as instruções descritas em Criar um projeto de aplicativo de função.

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

    • Por padrão, o tempo de execução do Azure Functions é definido como Azure Functions v3 (.NET Core). A Microsoft recomenda o uso desta versão do tempo de execução do Azure Functions.
    • Na lista de gatilhos possíveis, selecione Gatilho de grade de eventos. Para obter mais informações sobre por que um gatilho de Grade de Eventos é o tipo recomendado de gatilho para manipular um evento de Armazenamento de Blob com uma Função do Azure, consulte Usar uma função como manipulador de eventos para eventos de Grade de Eventos.
    • A configuração Conta de Armazenamento indica onde sua Função do Azure será armazenada. Você pode selecionar uma conta de armazenamento existente ou criar uma nova.

  3. Selecione Criar para criar o novo projeto no Visual Studio.

  4. Em seguida, renomeie a classe e a Função do Azure, conforme descrito em Renomear a função. Escolha um nome apropriado para o seu cenário.

  5. No Visual Studio, selecione Ferramentas | NuGet Package Manager | Console do Gerenciador de Pacotes e instale os seguintes pacotes do console:

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

  6. No arquivo de classe para sua Função do Azure, cole as seguintes instruções using:

    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. Este é o método que é executado quando ocorre um evento. Cole o código a seguir no corpo do método Run . Lembre-se de substituir os valores de espaço reservado 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 o desenvolvimento do Azure Functions, consulte Orientação para o desenvolvimento do Azure Functions.

Para saber mais sobre as informações incluídas quando um evento de Armazenamento de Blob é publicado em um manipulador de eventos, consulte Armazenamento de Blob do Azure como fonte de Grade de Eventos.

Execute a Função do Azure localmente no depurador

Para testar seu código do Azure Function localmente, você precisa enviar manualmente uma solicitação HTTP que dispara o evento. Você pode postar a solicitação usando uma ferramenta como Postman.

Na parte superior do arquivo de classe para sua Função do Azure está um ponto de extremidade de URL que você pode usar para testar no ambiente local. Postar a solicitação com essa URL dispara o evento no ambiente local para que você possa depurar seu código. O URL está no seguinte formato:

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

A solicitação que você envia para esse ponto de extremidade é uma solicitação simulada. Ele não envia nem recebe dados da sua conta de Armazenamento do 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 um novo pedido.

  2. Cole o URL mostrado acima no campo para o URL da solicitação, substituindo o nome da sua função e {functionname} removendo as chaves encaracoladas. Certifique-se de que o verbo de solicitação está definido como GET.

    Screenshot showing how to specify local URL for event trigger in Postman

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

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

    Screenshot showing header configuration for local request to trigger event

  5. Em Postman, especifique o corpo da solicitação, com o tipo de corpo definido como JSON e o formato como bruto. O exemplo a seguir simula uma solicitação de Blob de cópia. Substitua valores de espaço reservado entre colchetes angulares por seus próprios valores. Observe que não é necessário alterar valores de data/hora ou identificador, pois esta é 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 os pontos de interrupção desejados em seu código e pressione F5 para executar o depurador.

  7. Em Postman, selecione o 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 informações adicionais e exemplos, consulte 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 que é 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:

Screenshot showing the contents of the log blob in the Azure portal

Publicar a Função do Azure

Depois de testar sua Função do Azure localmente, a próxima etapa é publicar a Função do Azure no Aplicativo de Função do Azure que você criou anteriormente. A função deve ser publicada para que você possa configurar a Grade de Eventos para enviar eventos que acontecem 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 segure (ou clique com o botão direito do mouse) seu projeto do Azure Functions e escolha Publicar.

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

  3. Selecione Azure Function App (Windows) como o destino específico e, em seguida, escolha Avançar.

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

  5. Verifique se a caixa de seleção Executar do arquivo do pacote está marcada.

  6. Selecione Concluir 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 do serviço para o Application Insights não está configurada, poderá configurá-lo nesta página.

  8. Selecione o botão Publicar para começar a publicar a Função do Azure no Aplicativo de Função do Azure que você criou anteriormente.

    Screenshot showing page to publish Azure Function from Visual Studio

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

Inscrever-se em eventos de reidratação de blob a partir de uma conta de armazenamento

Agora você tem um aplicativo de função que contém uma Função do Azure que pode ser executada em resposta a um evento. O próximo passo é criar uma subscrição de evento a partir 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 em sua conta de armazenamento. Em seguida, 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 arquivamento são Microsoft.Storage.BlobTierChanged, correspondente a uma operação set Blob Tier, e Microsoft.Storage.BlobCreated eventos, correspondentes a uma operação Copy Blob. Dependendo do seu cenário, talvez você queira manipular apenas um desses eventos.

Para criar a subscrição do evento, siga estes passos:

  1. No portal do Azure, navegue até a conta de armazenamento que contém blobs para reidratar a partir da camada de arquivamento.

  2. Selecione a configuração Eventos no painel de navegação esquerdo.

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

  4. Selecione Criar assinatura de evento.

  5. Na página Criar Assinatura de Evento, na seção Detalhes da assinatura de evento, forneça um nome para a assinatura do 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 publicados pelo Armazenamento do Azure. Para obter mais informações sobre tópicos do sistema, consulte Tópicos do sistema na Grade de Eventos do Azure.

  7. Na seção Tipos de Evento , selecione os eventos Blob Created e Blob Tier Changed . Dependendo de como você optar por reidratar um blob da camada de arquivamento, um desses dois eventos será acionado.

    Screenshot showing how to select event types for blob rehydration events in the Azure portal

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

  9. Escolha Select an endpoint (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ção para sua Função do Azure. Finalmente, selecione o nome da função na lista suspensa e escolha Confirmar seleção.

    Screenshot showing how to select an Azure Function as the endpoint for an Event Grid subscription

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

Para saber mais sobre assinaturas de eventos, consulte Conceitos da Grade de Eventos do Azure.

Testar o manipulador de eventos do Azure Function

Para testar a Função do Azure, você pode disparar um evento na conta de armazenamento que contém a assinatura do evento. A assinatura de evento que você criou anteriormente está filtrando em dois eventos, Microsoft.Storage.BlobCreated e Microsoft.Storage.BlobTierChanged. Quando qualquer um desses eventos for acionado, ele acionará 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 da API é Copy Blob.
  • Quando o evento é Microsoft.Storage.BlobTierChanged e a operação de API é set Blob Tier.

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

Depois que a reidratação for concluída, o log blob é gravado no mesmo recipiente que o 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 original permanece na camada de arquivamento, 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.

Screenshot showing the original blob in the archive tier, the rehydrated blob in the hot tier, and the log blob written by the event handler.

Tenha em mente que reidratar uma bolha pode levar até 15 horas, dependendo da configuração de prioridade de reidratação. Se definir a prioridade de reidratação como Alta, a reidratação pode ser concluída em menos de uma hora para bolhas com menos de 10 GB de tamanho. No entanto, uma reidratação de alta prioridade incorre em um custo maior. Para obter mais informações, consulte Visão geral da reidratação de blob da camada de arquivamento.

Gorjeta

Embora o objetivo deste how-to seja lidar com esses eventos no contexto da reidratação de blob, para fins de teste também pode ser útil observar esses eventos em resposta ao upload de um blob ou alterar a camada de um blob online (ou seja, de quente para frio), porque o evento é acionado imediatamente.

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

Consulte também