Receba notificações sobre alterações por diferentes maneiras de envio(versão prévia)Get change notifications delivered in different ways (preview)

A alteração de notificações podem ser enviadas em diferentes maneiras aos assinantes.Change notifications can be delivered in different ways to subscribers. Se o modo de entrega principal para as notificações de alteração é através de webhooks, pode ser um desafio tira proveito do webhooks para cenários de alta produtividade ou quando o receptor não puder expor uma URL de notificação disponível publicamente.If the main delivery mode for change notifications is through webhooks, it can be challenging to take advantage of webhooks for high throughput scenarios or when the receiver cannot expose a publicly available notificiation URL.

Esse modo de entrega de notificações de alterações está disponível para todos os recursos que oferecem suporte a notificações de alterações do Microsoft Graph.This change notifications delivery mode is available for all resources that support Microsoft Graph change notifications.

Bons exemplos de cenários de alta produtividade incluem aplicações que subscrevem um grande conjunto de recursos, aplicações que subscrevem recursos que mudam com uma alta frequência e aplicações multi-locatárias que subscrevem recursos através de um grande conjunto de organizações.Good examples of high throughput scenarios include applications subscribing to a large set of resources, applications subscribing to resources that change with a high frequency, and multi-tenant applications that subscribe to resources accross a large set of organizations.

Usando os Hubs de Eventos do Azure para receber notificações de alteraçãoUsing Azure Event Hubs to receive change notifications

Os Hubs de Eventos do Azure é um serviço popular de inclusão e distribuição de eventos em tempo real, compilado para ser dimensionável.Azure Event Hubs is a popular real-time events ingestion and distribution service built for scale. Você pode usar os Hubs de Eventos do Azure, em vez de webhooks tradicionais, para receber notificações de alteração.You can use Azure Events Hubs instead of traditional webhooks to receive change notifications. Este recurso está atualmente no modo de visualização.This feature is currently in preview.
Usar os Hubs de Eventos do Azure para receber notificações de alteração difere do webhooks em algumas maneiras, incluindo:Using Azure Event Hubs to receive change notifications differs from webhooks in a few ways, including:

  • Você não depende de URLs com notificações publicamente expostas.You don't rely on publicly exposed notification URLs. O SDK do Hubs de Eventos retransmitirá as notificações para sua aplicação.The Event Hubs SDK will relay the notifications to your application.
  • Não é necessário responder à validação da URL de notificação.You don't need to reply to the notification URL validation. Você pode ignorar a mensagem de validação recebida.You can ignore the validation message that you receive.
  • Você precisará de provisionar um Hub de Eventos do Azure.You'll need to provision an Azure Event Hub.
  • Você precisará de provisionar um Azure Key Vault.You'll need to provision an Azure Key Vault.

Configurar o Cofre de Chaves do Azure e os Hubs de Eventos do AzureSet up the Azure KeyVault and Azure Event Hubs

Esta seção vai orientá-lo a configurar os necessários serviços do Azure.This section will walk you through the setup of required Azure services.

Opção 1: Usando o CLI do AzureOption 1: Using the Azure CLI

O CLI do Azure permite que você escreva o script e automatize tarefas administrativas no Azure.The Azure CLI allows you to script and automate adminstrative tasks in Azure. O CLI pode ser instalado em seu computador local ou ser executado diretamente a partir do Azure Cloud Shell.The CLI can be installed on your local computer or run directly from the Azure Cloud Shell.

# --------------
# TODO: update the following values
#sets the name of the resource group
resourcegroup=rg-graphevents-dev
#sets the location of the resources
location='uk south'
#sets the name of the Azure Event Hubs namespace
evhamespacename=evh-graphevents-dev
#sets the name of the hub under the namespace
evhhubname=graphevents
#sets the name of the access policy to the hub
evhpolicyname=grapheventspolicy
#sets the name of the Azure KeyVault
keyvaultname=kv-graphevents
#sets the name of the secret in Azure KeyVault that will contain the connection string to the hub
keyvaultsecretname=grapheventsconnectionstring
# --------------
az group create --location $location --name $resourcegroup
az eventhubs namespace create --name $evhamespacename --resource-group $resourcegroup --sku Basic --location $location
az eventhubs eventhub create --name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --partition-count 2 --message-retention 1
az eventhubs eventhub authorization-rule create --name $evhpolicyname --eventhub-name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --rights Send
evhprimaryconnectionstring=`az eventhubs eventhub authorization-rule keys list --name $evhpolicyname --eventhub-name $evhhubname --namespace-name $evhamespacename --resource-group $resourcegroup --query "primaryConnectionString" --output tsv`
az keyvault create --name $keyvaultname --resource-group $resourcegroup --location $location --enable-soft-delete true --sku standard --retention-days 90
az keyvault secret set --name $keyvaultsecretname --value $evhprimaryconnectionstring --vault-name $keyvaultname --output none
graphspn=`az ad sp list --display-name 'Microsoft Graph Change Tracking' --query "[].appId" --output tsv`
az keyvault set-policy --name $keyvaultname --resource-group $resourcegroup --secret-permissions get --spn $graphspn --output none
keyvaulturi=`az keyvault show --name $keyvaultname --resource-group $resourcegroup --query "properties.vaultUri" --output tsv`
domainname=`az ad signed-in-user show --query 'userPrincipalName' | cut -d '@' -f 2 | sed 's/\"//'`
notificationUrl="EventHub:${keyvaulturi}secrets/${keyvaultsecretname}?tenantId=${domainname}"
echo "Notification Url:\n${notificationUrl}"

Observação: O script fornecido aqui é compatível com shells baseados em Linux, Windows WSL e Azure Cloud Shell.Note: The script provided here is compatible with Linux based shells, Windows WSL, and Azure Cloud Shell. Será necessário algumas atualizações para executar shells do Windows.It will require some updates to run in Windows shells.

Opção 2: Usando o Portal do AzureOption 2: Using the Azure Portal

Configurando o Hub de eventos do AzureConfiguring the Azure Event Hub

Nesta seção, você vai:In this section you will:

  • Criar um namespace do Hub de Eventos do Azure.Create an Azure Event Hub namespace.
  • Adicionar um hub para este namespace que irá transmitir e entregar notificações.Add a hub to that namespace that will relay and deliver notifications.
  • Adicionar uma política de acesso compartilhado que permita obter uma cadeia de conexão para o hub recém-criado.Add a shared access policy that will allow you to get a connection string to the newly created hub.

Etapas:Steps:

  1. Abra um navegador para o Portal do Azure.Open a browser to the Azure Portal.
  2. Selecione Criar um recurso.Select Create a resource.
  3. Digite Hubs de Evento na barra de pesquisa.Type Event Hubs in the search bar.
  4. Selecione a sugestão Hubs de Eventos.Select the Event Hubs suggestion. A página de criação dos Hubs de Evento será carregada.The Event Hubs creation page will load.
  5. Na página de criação dos Hubs de Evento clique criar.On the Event Hubs creation page, click Create.
  6. Preencha os detalhes da criação no namespace dos Hubs de Eventos e clique em Criar.Fill in the Event Hubs namespace creation details, and then click Create.
  7. Quando o namespace do Hub de Eventos for provisionado, vá para a página do namespace.When the Event Hub namespace is provisioned, go to the page for the namespace.
  8. Clique em Hubs de Eventos e + Hub de Eventos.Click Event Hubs and + Event Hub.
  9. Dê um nome para o novo Hub de Eventos e clique em Criar.Give a name to the new Event Hub, and click Create.
  10. Depois que o Hub de Eventos foi criado, clique no nome do Hub de Eventos e, em seguida, clique em Políticas de acesso compartilhado e + Adicionar para adicionar uma nova política.After the Event Hub has been created, click the name of the Event Hub, and then click Shared access policies and + Add to add a new policy.
  11. Dê um nome à política, marque Enviar, e clique em Criar.Give a name to the policy, check Send, and click Create.
  12. Depois de criar a política, clique no nome da política para abrir o painel de detalhes e, em seguida, copie o valor da Chave principal da cadeia de conexão.After the policy has been created, click the name of the policy to open the details panel, and then copy the Connection string-primary key value. Anote-o; você precisará dele para a próxima etapa.Write it down; you'll need it for the next step.
Configurando o Azure Key VaultConfiguring the Azure Key Vault

Para acessar o Hub de Eventos de forma segura e permitir rotações de chaves, o Microsoft Graph obtém a cadeia de conexão para o Hub de Eventos através do Azure Key Vault.In order to access the Event Hub securely and to allow for key rotations, Microsoft Graph gets the connection string to the Event Hub through Azure Key Vault.
Nesta seção, você vai:In this section, you will:

  • Criar um Azure Key Vault para armazenar segredo.Create an Azure Key Vault to store secret.
  • Adicionar a cadeia de conexão ao Hub de Evento como um segredo.Add the connection string to the Event Hub as a secret.
  • Adicionar uma política de acesso para o Microsoft Graph acessar o segredo.Add an access policy for Microsoft Graph to access the secret.

Etapas:Steps:

  1. Abra um navegador para o Portal do Azure.Open a browser to the Azure Portal.
  2. Selecione Criar um recurso.Select Create a resource.
  3. Digite Cofre de Chaves na barra de pesquisa.Type Key Vault in the search bar.
  4. Selecione a sugestão do Cofre de Chaves.Select the Key Vault suggestion. A página de criação do Cofre de Chaves será carregada.The Key Vault creation page will load.
  5. Na página de criação do Cofre de Chaves clique criar.On the Key Vault creation page, click Create.
  6. Preencha os detalhes da criação do cofre de chaves e, em seguida, clique em Revisar + Criar e Criar.Fill in the Key Vault creation details, and then click Review + Create and Create.
  7. Vá para o cofre de chaves recém-criado usando Ir para o recurso da notificação.Go to the newly crated key vault using the Go to resource from the notification.
  8. Copie o nome do DNS; você precisará dele para a próxima etapa.Copy the DNS name; you will need it for the next step.
  9. Vá para Segredos e clique em + Gerar/Importar.Go to Secrets and click + Generate/Import.
  10. Dê um nome ao segredo e guarde-o para mais tarde; você precisará dele para a próxima etapa.Give a name to the secret, and keep the name for later; you will need it for the next step. Para o valor, cole a cadeia de conexão que você gerou na etapa Hubs de Eventos.For the value, paste in the connection string you generated at the Event Hubs step. Clique em Criar.Click Create.
  11. Clique em Políticas de Acesso e + Adicionar Política de Acesso.Click Access Policies and + Add Access Policy.
  12. Para Permissões de segredo, selecione Obter, e para Selecionar Principal, selecione Controle de Alterações do Microsoft Graph.For Secret permissions, select Get, and for Select Principal, select Microsoft Graph Change Tracking. Clique em Adicionar.Click Add.

Criando a assinatura e recebendo notificaçõesCreating the subscription and receiving notifications

Depois de você criar os serviços necessários Azure Key Vault e do Hubs de Eventos do Azure, você poderá criar sua assinatura e começar a receber as notificações de alteração por meio dos Hubs de Eventos do Azure.After you create the required Azure KeyVault and Azure Event Hubs services, you will be able to create your subscription and start receiving change notifications via Azure Event Hubs.

Criando a assinaturaCreating the subcription

As assinaturas para alterar as notificações com os Hubs de Eventos são quase idênticas como alterar as notificações com webhooks.Subscriptions to change notifications with Event Hubs are almost identical to change notifications with webhooks. A principal diferença é que elas dependem dos Hubs de Eventos para entregar notificações.The key difference is that they rely on Event Hubs to deliver notifications. Todas as outras operações são similares, inclusive a criação de assinatura.All other operations are similar, including subscription creation.

A principal diferença durante a criação da assinatura será o notificationUrl.The main difference during subscription creation will be the notificationUrl. Você deve defini-lo para EventHub:https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname> os seguintes valores:You must set it to EventHub:https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>, with the following values:

  • azurekeyvaultname - O nome que você atribuiu ao cofre de chaves quando o criou.azurekeyvaultname - The name you gave to the key vault when you created it. Pode ser encontrado no nome DNS.Can be found in the DNS name.
  • secretname - O nome que você atribuiu ao segredo quando o criou.secretname - The name you gave to the secret when you created it. Pode ser encontrado na página Segredos. do Azure Key Vault.Can be found on the Azure Key Vault Secrets page.
  • domainname – O nome do seu locatário do. por exemplo, consto.onmicrosoft.com ou contoso.com.domainname - The name of your tenant; for example, consto.onmicrosoft.com or contoso.com. Como esse domínio será usado para acessar o Azure Key Vault é importante que ele corresponda ao domínio usado pela assinatura do Azure que possui o Azure Key Vault.Because this domain will be used to access the Azure Key Vault, it is important that it matches the domain used by the Azure subscription that holds the Azure Key Vault. Para obter essa informação, você pode ir para a página de visão geral do Azure Key Vault que você criou e clique na assinatura.To get this information, you can go to the overview page of the Azure Key Vault you created and click the subscription. O nome de domínio é exibido sob o campo Diretório.The domain name is displayed under the Directory field.

Recebendo notificaçõesReceiving notifications

Os eventos agora serão enviados para o aplicativo através dos Hubs de Eventos.Events will be now delivered to your application by Event Hubs. Para detalhes, confira Recebendo eventos na documentação Hubs de Eventos.For details, see receiving events in the Event Hubs documentation.

Antes de receber as notificações no aplicativo, você precisará criar outra política de acesso compartilhado com uma permissão de "Escuta" e obter a cadeia de conexão, semelhante às etapas listadas em Configurando o Azure Event Hub.Before you can receive the notifications in your application, you'll need to create another shared access policy with a "Listen" permission and obtain the connection string, similar to the steps listed in Configuring the Azure Event Hub.

Observação: Criar uma política separada para o aplicativo que escuta mensagens de Hubs de Eventos, em vez de reutilizar a mesma cadeia de conexão que você definiu no Azure keyVault.Note: Create a separate policy for the application that listens to Event Hubs messages instead of reusing the same connection string you set in Azure KeyVault. Isto garante que cada componente da solução tenha apenas as permissões que precisa e siga o princípio de segurança com o mínimo de permissões.This ensures that each component of the solution has only the permissions it needs and follows the least permissions security principle.

Observação: Seu aplicativo recebe mensagens de validação sempre que criar uma nova assinatura.Note: Your application receives validation messages whenever it creates a new subscription. Você deve ignorar essas notificações.You should ignore these notifications. O exemplo a seguir representa o corpo de uma mensagem de validação.The following example represents the body of a validation message.

 {
    "value":[
        {
            "subscriptionId":"NA",
            "subscriptionExpirationDateTime":"NA",
            "clientState":"NA",
            "changeType":"Validation: Testing client application reachability for subscription Request-Id: 522a8e7e-096a-494c-aaf1-ac0dcfca45b7",
            "resource":"NA",
            "resourceData":{
                "@odata.type":"NA",
                "@odata.id":"NA",
                "id":"NA"
            }
        }
    ]
}

O que acontece se o aplicativo de controle de alterações do Microsoft Graph estiver ausente?What happens if the Microsoft Graph change tracking application is missing?

É possível que o serviço principal do Controle de Alterações do Microsoft Graph esteja ausente no seu locatário, dependendo de quando o locatário foi criado e de operações administrativas.It's possible that the Microsoft Graph Change Tracking service principal is missing from your tenant, depending on when the tenant was created and administrative operations. Para resolver este problema, execute a seguinte consulta no Microsoft Graph Explorer.To resolve this issue, run the following query in Microsoft Graph Explorer.

Detalhes da consulta:Query details:

POST https://graph.microsoft.com/v1.0/servicePrincipals
{
    "appId": "0bf30f3b-4a52-48df-9a82-234910c4a086"
}

Observação: Você pode obter um acesso negado ao executar esta consulta.Note: You can get an access denied running this query. Neste caso, selecione o ícone de engrenagem ao lado do nome da sua conta no canto superior esquerdo.In this case, select the gear icon next to your account name in the top left corner. Em seguida, selecione Selecionar Permissões e pesquise Application.ReadWrite.All.Then select Select Permissions and search for Application.ReadWrite.All. Marque a permissão e selecione Consentir.Check the permission and select Consent. Após o consentimento dessa nova permissão, execute a solicitação novamente.After consenting to this new permission, run the request again.

Observação: Esta API só funciona com uma conta corporativa ou de estudante e não com uma conta pessoal.Note: This API only works with a school or work account, not with a personal account. Certifique-se que você está conectado com uma conta no seu domínio.Make sure that you are signed in with an account on your domain.

Como alternativa, você pode usar este script do Azure Active Directory PowerShell para adicionar o serviço principal ausente.Alternatively, you can use this Azure Active Directory PowerShell script to add the missing service principal.

Connect-AzureAD -TenantId <tenant-id>
# replace tenant-id by the id of your tenant.
New-AzureADServicePrincipal -AppId 0bf30f3b-4a52-48df-9a82-234910c4a086

Próximas etapasNext steps

Confira os seguintes, inícios rápidos dos Hubs de Eventos do Azure:See the following Azure Event Hubs quick starts: