Partilhar via

Azure Event Grid biblioteca de cliente para .NET – versão 4.14.1

  • Artigo

O Azure Event Grid permite-lhe criar facilmente aplicações com arquiteturas baseadas em eventos. O serviço Event Grid gere totalmente todo o encaminhamento de eventos de qualquer origem, para qualquer destino, para qualquer aplicação. Os eventos de serviço do Azure e eventos personalizados podem ser publicados diretamente no serviço, onde os eventos podem ser filtrados e enviados para vários destinatários, como processadores incorporados ou webhooks personalizados. Para saber mais sobre Azure Event Grid: O que é o Event Grid?

Utilize a biblioteca de cliente para Azure Event Grid para:

Introdução

Instalar o pacote

Instale a biblioteca de cliente a partir do NuGet:

dotnet add package Azure.Messaging.EventGrid

Pré-requisitos

Tem de ter uma subscrição do Azure e um grupo de recursos do Azure com um tópico ou domínio personalizado do Event Grid. Siga este tutorial passo a passo para registar o fornecedor de recursos do Event Grid e criar tópicos do Event Grid com o portal do Azure. Existe um tutorial semelhante com a CLI do Azure.

Autenticar o Cliente

Para que a biblioteca de cliente interaja com um tópico ou domínio, precisará do endpoint tópico do Event Grid e de um credential, que pode ser criado com a chave de acesso do tópico.

Pode encontrar o ponto final do tópico do Event Grid no Portal do Azure ou através do fragmento da CLI do Azure abaixo.

az eventgrid topic show --name <your-resource-name> --resource-group <your-resource-group-name> --query "endpoint"

A chave de acesso também pode ser encontrada através do portal ou através do fragmento da CLI do Azure abaixo:

az eventgrid topic key list --name <your-resource-name> --resource-group <your-resource-group-name> --query "key1"

Autenticar com a Chave de Acesso ao Tópico

Assim que tiver a chave de acesso e o ponto final do tópico, pode criar o cliente do publicador da seguinte forma:

EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri("<endpoint>"),
    new AzureKeyCredential("<access-key>"));

Autenticar com a Assinatura de Acesso Partilhado

O Event Grid também suporta a autenticação com uma assinatura de acesso partilhado que permite fornecer acesso a um recurso que expira por um determinado período de tempo sem partilhar a sua chave de acesso. Geralmente, o fluxo de trabalho seria que uma aplicação geraria a cadeia de SAS e entregaria a cadeia a outra aplicação que consumiria a cadeia. Gerar a SAS:

var builder = new EventGridSasBuilder(new Uri(topicEndpoint), DateTimeOffset.Now.AddHours(1));
var keyCredential = new AzureKeyCredential(topicAccessKey);
string sasToken = builder.GenerateSas(keyCredential);

Eis como seria utilizado do ponto de vista do consumidor:

var sasCredential = new AzureSasCredential(sasToken);
EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri(topicEndpoint),
    sasCredential);

EventGridPublisherClient também aceita um conjunto de opções de configuração através de EventGridPublisherClientOptions. Por exemplo, pode especificar um serializador personalizado que será utilizado para serializar os dados do evento para JSON.

Autenticar com o Azure Active Directory

Azure Event Grid fornece integração com o Azure Active Directory (Azure AD) para autenticação baseada em identidade de pedidos. Com Azure AD, pode utilizar o controlo de acesso baseado em funções (RBAC) para conceder acesso aos seus recursos Azure Event Grid a utilizadores, grupos ou aplicações. A biblioteca de Identidade do Azure fornece suporte fácil do Azure Active Directory para autenticação.

Para enviar eventos para um tópico ou domínio com o Azure Active Directory, a identidade autenticada deve ter a função "Remetente de Dados do EventGrid" atribuída.

EventGridPublisherClient client = new EventGridPublisherClient(
    new Uri(topicEndpoint),
    new DefaultAzureCredential());

Conceitos-chave

Para obter informações sobre os conceitos gerais do Event Grid: Conceitos no Azure Event Grid.

EventGridPublisherClient

Um publicador envia eventos para o serviço Event Grid. A Microsoft publica eventos para vários serviços do Azure. Pode publicar eventos a partir da sua própria aplicação com o EventGridPublisherClient.

Esquemas de eventos

Um evento é a menor quantidade de informações que descreve totalmente algo que aconteceu no sistema. O Event Grid suporta vários esquemas para eventos de codificação. Quando é criado um tópico ou domínio personalizado, especifique o esquema que será utilizado ao publicar eventos.

Esquema do Event Grid

Embora possa configurar o tópico para utilizar um esquema personalizado, é mais comum utilizar o esquema do Event Grid já definido. Veja as especificações e os requisitos aqui.

Esquema CloudEvents v1.0

Outra opção é utilizar o esquema CloudEvents v1.0. O CloudEvents é um projeto do Cloud Native Computing Foundation que produz uma especificação para descrever os dados de eventos de uma forma comum. O resumo do serviço do CloudEvents pode ser encontrado aqui.

Independentemente do esquema que o seu tópico ou domínio está configurado para utilizar, EventGridPublisherClient será utilizado para publicar eventos no mesmo. Utilize o SendEvents método ou SendEventsAsync para publicar.

Entrega de eventos

Os eventos entregues aos consumidores pelo Event Grid são entregues como JSON. Dependendo do tipo de consumidor a que está a ser entregue, o serviço Event Grid pode fornecer um ou mais eventos como parte de um único payload. O processamento de eventos será diferente com base no esquema como o qual o evento foi entregue. No entanto, o padrão geral permanecerá o mesmo:

  • Analise eventos do JSON em eventos individuais. Com base no esquema de eventos (Event Grid ou CloudEvents), pode agora aceder a informações básicas sobre o evento no envelope (propriedades que estão presentes para todos os eventos, como a hora e o tipo do evento).
  • Anular a serialização dos dados do evento. Tendo em conta um EventGridEvent ou CloudEvent, o utilizador pode tentar aceder ao payload de eventos, ou dados, ao anular a serialização para um tipo específico. Pode fornecer um serializador personalizado neste momento para descodificar corretamente os dados.

Segurança de threads

Garantimos que todos os métodos de instância de cliente são seguros para threads e independentes uns dos outros (orientação). Isto garante que a recomendação de reutilização de instâncias de cliente é sempre segura, mesmo entre threads.

Conceitos adicionais

Opções de | cliente Aceder à resposta | Operações de execução prolongada | Lidar com falhas | Diagnósticos | A gozar | Duração do cliente

Exemplos

Publicar eventos do Event Grid num Tópico do Event Grid

A publicação de eventos no Event Grid é efetuada com o EventGridPublisherClient. Utilize o método fornecido SendEvent/SendEventAsync para publicar um único evento no tópico.

// Add EventGridEvents to a list to publish to the topic
EventGridEvent egEvent =
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        "This is the event data");

// Send the event
await client.SendEventAsync(egEvent);

Para publicar um lote de eventos, utilize o SendEvents/SendEventsAsync método .

// Example of a custom ObjectSerializer used to serialize the event payload to JSON
var myCustomDataSerializer = new JsonObjectSerializer(
    new JsonSerializerOptions()
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase
    });

// Add EventGridEvents to a list to publish to the topic
List<EventGridEvent> eventsList = new List<EventGridEvent>
{
    // EventGridEvent with custom model serialized to JSON
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        new CustomModel() { A = 5, B = true }),

    // EventGridEvent with custom model serialized to JSON using a custom serializer
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        myCustomDataSerializer.Serialize(new CustomModel() { A = 5, B = true })),
};

// Send the events
await client.SendEventsAsync(eventsList);

Publicar CloudEvents num Tópico do Event Grid

A publicação de eventos no Event Grid é efetuada com o EventGridPublisherClient. Utilize o método fornecido SendEvents/SendEventsAsync para publicar eventos no tópico.

// Example of a custom ObjectSerializer used to serialize the event payload to JSON
var myCustomDataSerializer = new JsonObjectSerializer(
    new JsonSerializerOptions()
    {
        PropertyNamingPolicy = JsonNamingPolicy.CamelCase
    });

// Add CloudEvents to a list to publish to the topic
List<CloudEvent> eventsList = new List<CloudEvent>
{
    // CloudEvent with custom model serialized to JSON
    new CloudEvent(
        "/cloudevents/example/source",
        "Example.EventType",
        new CustomModel() { A = 5, B = true }),

    // CloudEvent with custom model serialized to JSON using a custom serializer
    new CloudEvent(
        "/cloudevents/example/source",
        "Example.EventType",
        myCustomDataSerializer.Serialize(new CustomModel() { A = 5, B = true }),
        "application/json"),

    // CloudEvents also supports sending binary-valued data
    new CloudEvent(
        "/cloudevents/example/binarydata",
        "Example.EventType",
        new BinaryData(Encoding.UTF8.GetBytes("This is treated as binary data")),
        "application/octet-stream")};

// Send the events
await client.SendEventsAsync(eventsList);

Publicar eventos do Event Grid num Domínio do Event Grid

Um domínio de eventos é uma ferramenta de gestão para um grande número de tópicos do Event Grid relacionados com a mesma aplicação. Pode pensar nisso como um meta-tópico que pode ter milhares de tópicos individuais. Quando cria um domínio de eventos, é-lhe atribuído um ponto final de publicação semelhante ao de se tivesse criado um tópico no Event Grid.

Para publicar eventos em qualquer tópico num Domínio de Eventos, envie os eventos para o ponto final do domínio da mesma forma que faria para um tópico personalizado. A única diferença é que tem de especificar o tópico ao qual pretende que o evento seja entregue.

// Add EventGridEvents to a list to publish to the domain
// Don't forget to specify the topic you want the event to be delivered to!
List<EventGridEvent> eventsList = new List<EventGridEvent>
{
    new EventGridEvent(
        "ExampleEventSubject",
        "Example.EventType",
        "1.0",
        "This is the event data")
    {
        Topic = "MyTopic"
    }
};

// Send the events
await client.SendEventsAsync(eventsList);

Para enviar CloudEvents, a origem cloudEvent é utilizada como o tópico de domínio:

List<CloudEvent> eventsList = new List<CloudEvent>();

for (int i = 0; i < 10; i++)
{
    CloudEvent cloudEvent = new CloudEvent(
        // the source is mapped to the domain topic
        $"Subject-{i}",
        "Microsoft.MockPublisher.TestEvent",
        "hello")
    {
        Id = $"event-{i}",
        Time = DateTimeOffset.Now
    };
    eventsList.Add(cloudEvent);
}

await client.SendEventsAsync(eventsList);

Receber e Anular a Eliminação de Eventos

Existem vários serviços do Azure diferentes que atuam como processadores de eventos.

Nota: se utilizar Webhooks para a entrega de eventos do esquema do Event Grid, o Event Grid requer que prove a propriedade do ponto final do Webhook antes de começar a entregar eventos a esse ponto final. No momento da criação da subscrição de eventos, o Event Grid envia um evento de validação de subscrição para o ponto final, conforme visto abaixo. Saiba mais sobre como concluir o handshake aqui: entrega de eventos do Webhook. Para o esquema CloudEvents, o serviço valida a ligação com o método de opções HTTP. Saiba mais aqui: Validação do CloudEvents.

Assim que os eventos forem entregues ao processador de eventos, podemos anular a serialização do payload JSON numa lista de eventos.

Com EventGridEvent:

// Parse the JSON payload into a list of events
EventGridEvent[] egEvents = EventGridEvent.ParseMany(BinaryData.FromStream(httpContent));

Com CloudEvent:

var bytes = await httpContent.ReadAsByteArrayAsync();
// Parse the JSON payload into a list of events
CloudEvent[] cloudEvents = CloudEvent.ParseMany(new BinaryData(bytes));

Anular a serialização de dados de eventos

A partir daqui, pode-se aceder aos dados do evento ao anular a serialização para um tipo específico ao chamar ToObjectFromJson<T>() a Data propriedade. Para anular a serialização para o tipo correto, a EventType propriedade (Type para CloudEvents) ajuda a distinguir entre diferentes eventos. Os dados de eventos personalizados devem ser desseriais com o método ToObjectFromJson<T>()genérico . Existe também um método ToObject<T>() de extensão que aceita um personalizado ObjectSerializer para anular a serialização dos dados do evento.

foreach (CloudEvent cloudEvent in cloudEvents)
{
    switch (cloudEvent.Type)
    {
        case "Contoso.Items.ItemReceived":
            // By default, ToObjectFromJson<T> uses System.Text.Json to deserialize the payload
            ContosoItemReceivedEventData itemReceived = cloudEvent.Data.ToObjectFromJson<ContosoItemReceivedEventData>();
            Console.WriteLine(itemReceived.ItemSku);
            break;
        case "MyApp.Models.CustomEventType":
            // One can also specify a custom ObjectSerializer as needed to deserialize the payload correctly
            TestPayload testPayload = cloudEvent.Data.ToObject<TestPayload>(myCustomSerializer);
            Console.WriteLine(testPayload.Name);
            break;
        case SystemEventNames.StorageBlobDeleted:
            // Example for deserializing system events using ToObjectFromJson<T>
            StorageBlobDeletedEventData blobDeleted = cloudEvent.Data.ToObjectFromJson<StorageBlobDeletedEventData>();
            Console.WriteLine(blobDeleted.BlobType);
            break;
    }
}

Com TryGetSystemEventData():

Se esperar maioritariamente eventos do sistema, poderá ser mais limpo ativar TryGetSystemEventData() e utilizar a correspondência de padrões para agir sobre os eventos individuais. Se um evento não for um evento de sistema, o método devolverá falso e o parâmetro de saída será nulo.

Como uma ressalva, se estiver a utilizar um tipo de evento personalizado com um valor EventType que posteriormente é adicionado como um evento de sistema pelo serviço e pelo SDK, o valor devolvido de TryGetSystemEventData mudaria de false para true. Isto pode surgir se estiver a criar preventivamente os seus próprios eventos personalizados para eventos que já estão a ser enviados pelo serviço, mas que ainda não foram adicionados ao SDK. Neste caso, é melhor utilizar o método genérico ToObjectFromJson<T> na propriedade para que o Data fluxo de código não seja alterado automaticamente após a atualização (é claro que poderá continuar a querer modificar o código para consumir o modelo de eventos do sistema recentemente lançado em oposição ao modelo personalizado).

foreach (EventGridEvent egEvent in egEvents)
{
    // If the event is a system event, TryGetSystemEventData will return the deserialized system event
    if (egEvent.TryGetSystemEventData(out object systemEvent))
    {
        switch (systemEvent)
        {
            case SubscriptionValidationEventData subscriptionValidated:
                Console.WriteLine(subscriptionValidated.ValidationCode);
                break;
            case StorageBlobCreatedEventData blobCreated:
                Console.WriteLine(blobCreated.BlobType);
                break;
            // Handle any other system event type
            default:
                Console.WriteLine(egEvent.EventType);
                // we can get the raw Json for the event using Data
                Console.WriteLine(egEvent.Data.ToString());
                break;
        }
    }
    else
    {
        switch (egEvent.EventType)
        {
            case "MyApp.Models.CustomEventType":
                TestPayload deserializedEventData = egEvent.Data.ToObjectFromJson<TestPayload>();
                Console.WriteLine(deserializedEventData.Name);
                break;
            // Handle any other custom event type
            default:
                Console.Write(egEvent.EventType);
                Console.WriteLine(egEvent.Data.ToString());
                break;
        }
    }
}

Resolução de problemas

Respostas do Serviço

SendEvents() devolve um código de resposta HTTP do serviço. Um RequestFailedException é emitido como uma resposta de serviço para quaisquer pedidos sem êxito. A exceção contém informações sobre que código de resposta foi devolvido do serviço.

Anular a serialização dos Dados de Eventos

  • Se os dados do evento não forem JSON válidos, será emitido um JsonException quando chamar Parse ou ParseMany.
  • Se o esquema do evento não corresponder ao tipo que está a ser desserializado (por exemplo, a chamar CloudEvent.Parse num evento EventGridSchema), é emitido um ArgumentException .
  • Se Parse for chamado para dados que contenham vários eventos, é emitido um ArgumentException . ParseMany deve ser utilizado aqui.

Configurar o registo da consola

Também pode ativar facilmente o registo da consola se quiser aprofundar os pedidos que está a fazer contra o serviço.

Rastreio Distribuído

A biblioteca do Event Grid suporta a distribuição do rastreio fora da caixa. Para cumprir a documentação de orientação da especificação CloudEvents sobre a distribuição do rastreio, a biblioteca definirá o traceparent e tracestate no de quando CloudEvent o ExtensionAttributes rastreio distribuído estiver ativado. Para saber mais sobre como ativar o rastreio distribuído na sua aplicação, veja a documentação de rastreio distribuído do SDK do Azure.

Event Grid no Kubernetes

Esta biblioteca foi testada e validada no Kubernetes com o Azure Arc.

Passos seguintes

Veja mais https://github.com/Azure/azure-sdk-for-net/blob/Azure.Messaging.EventGrid_4.14.1/sdk/eventgrid/Azure.Messaging.EventGrid/samples aqui para obter utilizações comuns da biblioteca de cliente do Event Grid: Exemplos do Event Grid.

Contribuir

Agradecemos todas as contribuições e sugestões para este projeto. A maioria das contribuições requerem que celebre um Contrato de Licença de Contribuição (CLA) no qual se declare que tem o direito de conceder e que, na verdade, concede-nos os direitos para utilizar a sua contribuição. Para obter detalhes, visite https://cla.microsoft.com.

Quando submete um pedido Pull, um bot do CLA determina automaticamente se tem de fornecer um CLA e decorar o PR de forma adequada (por exemplo, etiqueta, comentário). Só tem de seguir as instruções fornecidas pelo bot. Apenas terá de fazer isto uma vez em todos os repositórios com o nosso CLA.

Este projeto adotou o Microsoft Open Source Code of Conduct (Código de Conduta do Microsoft Open Source). Para obter mais informações, consulte as FAQ do Código de Conduta ou o contacto opencode@microsoft.com com quaisquer perguntas ou comentários adicionais.

Impressões