Grade de Eventos do Azure biblioteca de clientes para Java – versão 4.19.0

Artigo
10/24/2023

A Grade de Eventos do Azure permite compilar facilmente aplicativos com as arquiteturas baseadas em evento. O serviço grade de eventos gerencia totalmente todo o roteamento de eventos de qualquer origem, para qualquer destino, para qualquer aplicativo. 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 manipuladores internos ou webhooks personalizados. Para saber mais sobre Grade de Eventos do Azure: O que é a Grade de Eventos?

Use a biblioteca de clientes para Grade de Eventos do Azure para:

Publicar eventos no serviço da Grade de Eventos usando o Evento da Grade de Eventos, o Evento de Nuvem 1.0 ou esquemas personalizados
Consumir eventos que foram entregues a manipuladores de eventos
Gerar tokens SAS para autenticar os eventos de publicação do cliente em tópicos Grade de Eventos do Azure

Fontes | Documentação | de referência da API Documentação do | produtoAmostras

Introdução

Pré-requisitos

JDK (Java Development Kit) com a versão 8 ou superior
Uma assinatura do Azure
Um tópico ou domínio da Grade de Eventos . Para criar o recurso, você pode usar portal do Azure ou a CLI do Azure

Se você usar a CLI do Azure, substitua <your-resource-group-name> e <your-resource-name> por seus próprios nomes exclusivos e <location> por um local de serviço válido do Azure.

Criando um tópico (CLI do Azure)

az eventgrid topic create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

Criando um domínio (CLI do Azure)

az eventgrid domain create --location <location> --resource-group <your-resource-group-name> --name <your-resource-name>

Incluir o pacote

Incluir o arquivo da BOM

Inclua o azure-sdk-bom em seu projeto para assumir a dependência da versão ga da biblioteca. No trecho a seguir, substitua o espaço reservado {bom_version_to_target} pelo número de versão. Para saber mais sobre a BOM, consulte o BOM README do SDK do AZURE.

<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-sdk-bom</artifactId>
            <version>{bom_version_to_target}</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

Depois, inclua a dependência direta na seção de dependências sem a marca de versão.

<dependencies>
  <dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventgrid</artifactId>
  </dependency>
</dependencies>

Incluir dependência direta

Se você quiser assumir a dependência de uma versão específica da biblioteca que não está presente na BOM, adicione a dependência direta ao seu projeto da seguinte maneira.

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-messaging-eventgrid</artifactId>
    <version>4.19.0</version>
</dependency>

Autenticar o Cliente

Para enviar eventos, precisamos de um ponto de extremidade para o qual enviar e alguma autenticação para o ponto de extremidade. A autenticação pode ser uma credencial de chave, uma assinatura de acesso compartilhado ou uma autenticação de token do Azure Active Directory. O ponto de extremidade e a chave podem ser obtidos por meio do Portal do Azure ou da CLI do Azure.

Ponto de extremidade

O ponto de extremidade está listado no dashboard do tópico ou domínio no Portal do Azure ou pode ser obtido usando o comando a seguir na CLI do Azure.

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

Chave de Acesso

As chaves estão listadas na guia "Chaves de Acesso" do Portal do Azure ou podem ser obtidas usando o comando a seguir na CLI do Azure. Qualquer uma das chaves listadas funcionará.

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

Autenticação de token do AAD (Azure Active Directory)

Grade de Eventos do Azure fornece integração com o Azure Active Directory (Azure AD) para autenticação baseada em identidade de solicitações. Com Azure AD, você pode usar o RBAC (controle de acesso baseado em função) para conceder acesso aos recursos de Grade de Eventos do Azure a usuários, grupos ou aplicativos. Para enviar eventos para um tópico ou domínio com um TokenCredential, a identidade autenticada deve ter a função "EventGrid Data Sender" atribuída.

Criando o cliente

Usando o ponto de extremidade e a chave de acesso para criar o cliente

Depois de ter a chave de acesso e o ponto de extremidade do tópico, você poderá criar o cliente do publicador da seguinte maneira:

Cliente de sincronização que funciona para todos os desenvolvedores Java:

// For CloudEvent
EventGridPublisherClient<CloudEvent> cloudEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildCloudEventPublisherClient();

// For EventGridEvent
EventGridPublisherClient<EventGridEvent> eventGridEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts EventGridEvent schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildEventGridEventPublisherClient();

// For custom event
EventGridPublisherClient<BinaryData> customEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts custom event schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildCustomEventPublisherClient();

ou cliente assíncrono se sua pilha de tecnologia tiver programação reativa, como reator de projeto:

// For CloudEvent
EventGridPublisherAsyncClient<CloudEvent> cloudEventAsyncClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildCloudEventPublisherAsyncClient();

// For EventGridEvent
EventGridPublisherAsyncClient<EventGridEvent> eventGridEventAsyncClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts EventGridEvent schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildEventGridEventPublisherAsyncClient();

// For custom event
EventGridPublisherAsyncClient<BinaryData> customEventAsyncClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts custom event schema>")
    .credential(new AzureKeyCredential("<key for the endpoint>"))
    .buildCustomEventPublisherAsyncClient();

Usando o ponto de extremidade e o token SAS para criar o cliente

Se você tiver uma SAS (Assinatura de Acesso Compartilhado) que pode ser usada para enviar eventos para um Tópico ou Domínio da Grade de Eventos por tempo limitado, você poderá usá-la para criar o cliente editor:

Cliente de sincronização:

EventGridPublisherClient<CloudEvent> cloudEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new AzureSasCredential("<sas token that can access the endpoint>"))
    .buildCloudEventPublisherClient();

Cliente assíncrono:

EventGridPublisherAsyncClient<CloudEvent> cloudEventAsyncClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new AzureSasCredential("<sas token that can access the endpoint>"))
    .buildCloudEventPublisherAsyncClient();

Usando o ponto de extremidade e a credencial de token do AAD (Azure Active Directory) para criar o cliente

Para usar a credencial de token do AAD, inclua azure-identity o artefato como uma dependência. Consulte LEIAME de identidade do azure para obter detalhes.

Cliente de sincronização:

EventGridPublisherClient<CloudEvent> cloudEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildCloudEventPublisherClient();

Cliente assíncrono:

EventGridPublisherAsyncClient<CloudEvent> cloudEventClient = new EventGridPublisherClientBuilder()
    .endpoint("<endpoint of your event grid topic/domain that accepts CloudEvent schema>")
    .credential(new DefaultAzureCredentialBuilder().build())
    .buildCloudEventPublisherAsyncClient();

Criar um token SAS para outras pessoas enviarem eventos por um período limitado

Se você quiser conceder permissão a outras pessoas para publicar eventos em seu Tópico ou Domínio da Grade de Eventos por algum tempo, crie uma SAS (Assinatura de Acesso Compartilhado) para que elas possam criar uma EventGridPublisherClient semelhante à acima para usar AzureSasCredential para criar o cliente editor.

Aqui está o código de exemplo para criar uma assinatura de acesso compartilhado que expira após 20 minutos:

OffsetDateTime expiration = OffsetDateTime.now().plusMinutes(20);
String sasToken = EventGridPublisherClient
    .generateSas("<your event grid endpoint>", new AzureKeyCredential("<key for the endpoint>"), expiration);

Use `BinaryData`.

Esse SDK usa com.azure.util.BinaryData para representar o conteúdo de dados de eventos. BinaryData dá suporte à serialização e desserialização de objetos por meio com.azure.core.util.BinaryData.fromObject(Object object) de métodos e toObject() , que usam um serializador Jackson Json padrão ou fromObject(Object object, ObjectSerializer customSerializer) métodos , toObject(Class<T> clazz, ObjectSerializer serializer) que aceitam seu serializador Json personalizado. Consulte a documentação binaryData para obter detalhes.

Principais conceitos

Para obter informações sobre conceitos gerais da Grade de Eventos: Conceitos em Grade de Eventos do Azure.

EventGridPublisherClient

EventGridPublisherClient é usado enviando eventos para um Tópico da Grade de Eventos ou um Domínio da Grade de Eventos. EventGridPublisherAsyncClient é a versão assíncrona do EventGridPublisherClient.

Esquemas de evento

A Grade de Eventos dá suporte a vários esquemas para eventos de codificação. Quando um Tópico ou Domínio da Grade de Eventos é criado, você especifica o esquema que será usado ao publicar eventos. Embora você possa configurar seu tópico para usar um esquema personalizado , é mais comum usar o esquema EventGridEvent já definido ou o esquema CloudEvent. CloudEvent é um projeto da Cloud Native Computing Foundation que produz uma especificação para descrever dados de evento de maneira comum. O serviço grade de eventos é compatível com a especificação CloudEvent Independentemente do esquema que seu tópico ou domínio está configurado para usar, EventGridPublisherClient será usado para publicar eventos nele. No entanto, você deve usar o tipo correto para instanciá-lo:

Esquema do evento	Instanciação genérica do cliente publisher
Eventos da Grade de Eventos	`EventGridPublisherClient<EventGridEvent>`
Eventos de nuvem	`EventGridPublisherClient<CloudEvent>`
Eventos personalizados	`EventGridPublisherClient<BinaryData>`

Usar o tipo errado resultará em um erro BadRequest do serviço e seus eventos não serão publicados. Use este comando da CLI do Azure para consultar qual esquema um Tópico ou Domínio da Grade de Eventos aceita:

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

Manipuladores de eventos e desserialização de eventos.

O EventGrid não armazena nenhum evento no Tópico da Grade de Eventos nem no próprio domínio. Você precisa criar assinaturas para o Tópico ou Domínio do EventGrid. Os eventos enviados para o tópico ou domínio serão armazenados no ponto de extremidade da assinatura, também conhecido como "Manipulador de Eventos".

Você pode usar o SDK do manipulador de eventos para receber os eventos na cadeia de caracteres Json e, em seguida, usar ou EventGridEvent.fromString()CloudEvent.fromString() desserializar os eventos. A parte de dados dos eventos pode estar em dados binários, string ou JSON.

Exemplos

Enviando eventos para tópicos da Grade de Eventos

Os eventos podem ser enviados no , CloudEventou em EventGridEventum esquema personalizado, conforme detalhado em Esquemas de Eventos. O tópico ou domínio deve ser configurado para aceitar o esquema que está sendo enviado. Para simplificar, o cliente síncrono é usado para amostras, no entanto, o cliente assíncrono tem os mesmos nomes de método.

Observação: descubra qual esquema (evento de nuvem, evento de grade de eventos ou evento personalizado) o tópico da grade de eventos aceita antes de começar a enviar.

Enviando `EventGridEvent` para um tópico que aceita o esquema EventGridEvent

// Make sure that the event grid topic or domain you're sending to is able to accept the EventGridEvent schema.
List<EventGridEvent> events = new ArrayList<>();
User user = new User("John", "James");
events.add(new EventGridEvent("exampleSubject", "Com.Example.ExampleEventType", BinaryData.fromObject(user), "0.1"));
eventGridEventClient.sendEvents(events);

Enviar `CloudEvent` para um tópico que aceita o esquema CloudEvent

// Make sure that the event grid topic or domain you're sending to is able to accept the CloudEvent schema.
List<CloudEvent> events = new ArrayList<>();
User user = new User("John", "James");
events.add(new CloudEvent("https://source.example.com", "Com.Example.ExampleEventType",
    BinaryData.fromObject(user), CloudEventDataFormat.JSON, "application/json"));
cloudEventClient.sendEvents(events);

Enviando eventos personalizados para um tópico que aceita o esquema de evento personalizado

// Make sure that the event grid topic or domain you're sending to is able to accept the custom event schema.
List<BinaryData> events = new ArrayList<>();
events.add(BinaryData.fromObject(new HashMap<String, String>() {
    {
        put("id", UUID.randomUUID().toString());
        put("time", OffsetDateTime.now().toString());
        put("subject", "Test");
        put("foo", "bar");
        put("type", "Microsoft.MockPublisher.TestEvent");
        put("data", "example data");
        put("dataVersion", "0.1");
    }
}));
customEventClient.sendEvents(events);

Enviando eventos para o domínio da grade de eventos

Um Domínio da Grade de Eventos pode ter milhares de tópicos, mas tem um único ponto de extremidade. Você pode usar um domínio para gerenciar um conjunto de tópicos relacionados. Enviar eventos para os tópicos de um Domínio da Grade de Eventos é o mesmo que enviar eventos para um Tópico da Grade de Eventos regular, exceto que você precisa especificar o topic de um EventGridEvent se o domínio aceitar EventGridEvent esquema.

List<EventGridEvent> events = new ArrayList<>();
User user = new User("John", "James");
events.add(new EventGridEvent("com/example", "Com.Example.ExampleEventType", BinaryData.fromObject(user), "1")
    .setTopic("yourtopic"));
eventGridEventClient.sendEvents(events);

Se o domínio aceitar CloudEvent o esquema, o atributo do CloudEvent configurado para mapear o topic quando o domínio for criado deverá ser definido. O atributo de mapeamento padrão é source.

Recebendo e consumindo eventos

O serviço grade de eventos não armazena eventos. Portanto, esse SDK da Grade de Eventos não tem um receptor de evento. Em vez disso, os eventos são armazenados nos Manipuladores de Eventos, incluindo ServiceBus, EventHubs, Fila de Armazenamento, ponto de extremidade WebHook ou muitos outros Serviços do Azure com suporte. No entanto, atualmente todos os eventos serão enviados e armazenados como dados JSON codificados. Aqui está um código básico que detalha a desserialização de eventos depois que eles são recebidos pelos manipuladores de eventos. Novamente, a manipulação é diferente com base no esquema de evento que está sendo recebido do tópico/assinatura.

Desserializar `EventGridEvent` ou `CloudEvent` de uma cadeia de caracteres Json

A cadeia de caracteres Json pode ter um único evento ou uma matriz de eventos. O resultado retornado é uma lista de eventos.

// Deserialize an EventGridEvent
String eventGridEventJsonData = "<your EventGridEvent json String>";
List<EventGridEvent> eventGridEvents = EventGridEvent.fromString(eventGridEventJsonData);

// Deserialize a CloudEvent
String cloudEventJsonData = "<your CloudEvent json String>";
List<CloudEvent> cloudEvents = CloudEvent.fromString(cloudEventJsonData);

Desserializar dados de um `CloudEvent` ou `EventGridEvent`

Depois de desserializar o EventGridEvent ou CloudEvent de uma cadeia de caracteres Json, você poderá usar getData()CloudEvent ou EventGridEvent para obter o conteúdo do evento. Ele retorna um BinaryData objeto , que tem métodos para desserializar ainda mais os dados em tipos utilizáveis:

BinaryData.toBytes() obtém os dados como um byte[]
BinaryData.toString() obtém os dados como uma cadeia de caracteres
BinaryData.toObject() obtém os dados como um objeto de um tipo específico. Ele usa o desserializador Json por padrão. Ele tem uma sobrecarga para aceitar seu desserializador se você quiser usar o seu próprio.

BinaryData eventData = eventGridEvent.getData();

//Deserialize data to a model class
User dataInModelClass = eventData.toObject(User.class);

//Deserialize data to a Map
Map<String, Object> dataMap = eventData.toObject(new TypeReference<Map<String, Object>>() {
});

//Deserialize Json String to a String
String dataString = eventData.toObject(String.class);

//Deserialize String data to a String
String dataInJsonString = eventData.toString();

//Deserialize data to byte array (byte[])
byte[] dataInBytes = eventData.toBytes();

Desserializar dados de eventos do sistema de `CloudEvent` ou `EventGridEvent`

Um evento enviado para um Tópico do Sistema é chamado de Evento de Tópico do Sistema ou Evento do Sistema. Um tópico do sistema na Grade de Eventos representa eventos publicados por uma Origem do Evento, como Armazenamento do Azure, Hubs de Eventos do Azure, Configuração de Aplicativos e assim por diante. Um exemplo é quando um blob é criado, um evento do sistema com o tipo de evento "Microsoft.Storage.BlobCreated" é enviado para o Tópico do Sistema configurado. A classe de evento do sistema para esse tipo de evento é StorageBlobCreatedEventData definida no pacote com.azure.messaging.eventgrid.systemevents. O EventGrid tem eventos do sistema para:

Configuração de Aplicativos do Azure
Serviço de Aplicativo do Azure
Armazenamento de Blobs do Azure
...
Consulte os serviços do Azure que dão suporte a tópicos do sistema para muitos outros serviços.
Consulte o pacote com.azure.messaging.eventgrid.systemevents para as classes de evento do sistema relacionadas

Não é possível enviar um Evento do Sistema para um Tópico do Sistema usando este SDK.

Receber e consumir eventos do sistema é o mesmo que outros eventos. Além disso, um conjunto de classes de modelo para os vários dados de evento do sistema são definidos no pacote com.azure.messaging.eventgrid.systemevents. Você pode fazer o seguinte depois de desserializar um evento usando EventGridEvent.fromString() ou CloudEvent.fromString():

procure a classe de modelo de dados de evento do sistema para a qual os dados do Evento do Sistema podem ser desserializados;

// Look up the System Event data class
Class<?> eventDataClazz = SystemEventNames.getSystemEventMappings().get(event.getEventType());

desserializar os dados de um evento do sistema para uma instância de classe de modelo, como desserializar quaisquer outros dados de evento;

// Deserialize the event data to an instance of a specific System Event data class type
BinaryData data = event.getData();
if (data != null) {
    StorageBlobCreatedEventData blobCreatedData = data.toObject(StorageBlobCreatedEventData.class);
    System.out.println(blobCreatedData.getUrl());
}

lidar com vários tipos de evento.

List<EventGridEvent> eventGridEvents = EventGridEvent.fromString("<Your EventGridEvent Json String>");
for (EventGridEvent eventGridEvent : eventGridEvents) {
    BinaryData binaryData = eventGridEvent.getData();
    switch (eventGridEvent.getEventType()) {
        case SystemEventNames.APP_CONFIGURATION_KEY_VALUE_DELETED:
            AppConfigurationKeyValueDeletedEventData keyValueDeletedEventData =
                binaryData.toObject(TypeReference.createInstance(AppConfigurationKeyValueDeletedEventData.class));
            System.out.println("Processing the AppConfigurationKeyValueDeletedEventData...");
            System.out.printf("The key is: %s%n", keyValueDeletedEventData.getKey());
            break;
        case SystemEventNames.APP_CONFIGURATION_KEY_VALUE_MODIFIED:
            AppConfigurationKeyValueModifiedEventData keyValueModifiedEventData =
                binaryData.toObject(TypeReference.createInstance(AppConfigurationKeyValueModifiedEventData.class));
            System.out.println("Processing the AppConfigurationKeyValueModifiedEventData...");
            System.out.printf("The key is: %s%n", keyValueModifiedEventData.getKey());
            break;
        default:
            System.out.printf("%s isn't an AppConfiguration event data%n", eventGridEvent.getEventType());
            break;
    }
}

Mais exemplos

Alguns códigos de exemplo adicionais podem ser encontrados aqui.

Solução de problemas

Respostas e códigos de erro

As respostas de serviço são retornadas na forma de códigos http status, incluindo vários códigos de erro. Opcionalmente, esses códigos podem ser retornados pelo PublisherClient. Códigos de status inesperados são lançados como HttpResponseException o que encapsula o código de erro.

A documentação de referência para o serviço de grade de eventos pode ser encontrada aqui. Esse é um bom lugar para começar para problemas que envolvem a configuração de tópicos/pontos de extremidade, bem como para problemas que envolvem códigos de erro do serviço.

Rastreamento distribuído

A biblioteca da Grade de Eventos dá suporte à distribuição do rastreamento pronto para uso. Para aderir às diretrizes da especificação CloudEvents sobre a distribuição de rastreamento, a biblioteca define traceparent e tracestate no extensionAttributes de um CloudEvent quando o rastreamento distribuído está habilitado. Para saber como habilitar o rastreamento distribuído em seu aplicativo, confira a documentação de rastreamento distribuído Java do SDK do Azure.

Ajuda e problemas

A documentação de referência do SDK pode ser encontrada aqui. Essa é uma boa primeira etapa para entender a finalidade de cada método chamado, bem como possíveis motivos para erros ou comportamento inesperado.

Se você encontrar bugs com esses SDKs, registre problemas por meio de Problemas ou check-out do StackOverflow para o SDK do Java do Azure.

Próximas etapas

Azure Java SDKs
Se você não tiver uma assinatura do Microsoft Azure, poderá obter uma conta de avaliação GRATUITA aqui
Alguns códigos de exemplo adicionais podem ser encontrados aqui
Tutoriais adicionais da Grade de Eventos podem ser encontrados aqui

Participante

Para obter detalhes sobre como contribuir para esse repositório, consulte o guia de contribuição.

Bifurcar
Criar seu branch de recurso (git checkout -b my-new-feature)
Confirmar suas alterações (git commit -am 'Add some feature')
Enviar por push para o branch (git push origin my-new-feature)
Criar nova solicitação de pull

Este projeto adotou o Código de Conduta de Software Livre da Microsoft. Para obter mais informações, confira as Perguntas frequentes sobre o Código de Conduta ou contate opencode@microsoft.com para enviar outras perguntas ou comentários.

Impressões

Partilhar via