Получение уведомлений об изменениях через Центры событий Azure

Веб-перехватчики могут не подходить для получения уведомлений об изменениях в сценариях с высокой пропускной способностью или когда получатель не может предоставить общедоступный URL-адрес уведомления. В качестве альтернативы можно использовать Центры событий Azure.

Хорошими примерами сценариев с высокой пропускной способностью являются приложения, подписывающиеся на большой набор ресурсов, приложения, подписывающиеся на ресурсы, которые изменяются с высокой частотой, и мультитенантные приложения, которые подписываются на ресурсы в большом наборе организаций.

В этой статье описывается процесс управления подпиской Microsoft Graph и получение уведомлений об изменениях через Центры событий Azure.

Получение уведомлений об изменениях с помощью концентраторов событий Azure

Концентраторы событий Azure — это сервис приема и распространения популярных событий в режиме реального времени, созданный для масштабирования. Для получения уведомлений об изменениях вместо традиционных веб-перехватчиков можно использовать концентраторы событий Azure.
Использование концентраторов событий Azure для получения уведомлений о изменениях отличается от веб-перехватчиков несколькими моментами, в том числе:

• Не приходится полагаться на общедоступные URL-адреса уведомлений. Пакет SDK концентраторов событий ретранслирует уведомления в ваше приложение.
• Нет необходимости отвечать на проверку URL-адреса уведомлений. Можно пропустить полученное сообщение о проверке.
• Необходимо подготовить концентратор событий Azure.
• Необходимо подготовить хранилище Azure Key Vault.

Настройка хранилища Azure Key Vault и концентраторов событий Azure

В этом разделе вы узнаете, как выполнить настройку обязательных служб Azure.

Использование интерфейса командной строки Azure

Средство Azure CLI позволяет создавать сценарии и автоматизировать админстративные задачи в Azure. Средство CLI можно установить на локальный компьютер или запустить напрямую в 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}"

Примечание. Представленный здесь сценарий совместим с оболочками на основе Linux, Windows WSL и Azure Cloud Shell. При этом для запуска в оболочках Windows необходимо сделать несколько обновлений.

Использование портал Azure

Настройка концентратора событий Azure

В этом разделе вы сделаете следующее:

• Создадите пространство имен концентратора событий Azure.
• Добавите в это пространство имен концентратор, который будет пересылать и доставлять уведомления.
• Добавите политику общего доступа, которая позволит получить строку подключения к только что созданному концентратору.

Шаги:

1. Откройте портал Azure в браузере.
2. Выберите Создать ресурс.
3. В строке поиска введите концентраторы событий.
4. Выберите концентраторы событий из предложенных. Будет загружена страница создания концентраторов событий.
5. На странице создания концентраторов событий нажмите Создать.
6. Заполните сведения о создании пространства имен концентраторов событий и выберите Cоздать.
7. Если пространство имен концентратора событий подготовлено, перейдите к странице пространства имен.
8. Щелкните Концентраторы событий и + Концентратор событий.
9. Введите имя нового концентратора событий и щелкните Создать.
10. После того как концентратор событий создан, щелкните на его имя, затем Политики общего доступа, а затем + Добавить, чтобы добавить новую политику.
11. Введите имя политики, установите флажок Отправитьи нажмите Создать.
12. Когда политика создана, щелкните на ее имя, чтобы открыть область сведений, и скопируйте значение Первичный ключ строки подключения. Запишите его, так как он понадобится в следующем шаге.

Настройка хранилища Azure Key Vault

Для безопасного доступа к концентратору событий и обеспечения ротации ключей Microsoft Graph отправляет строку подключения в концентратор событий через хранилище Azure Key Vault.
В этом разделе вы сделаете следующее:

• Создадите хранилище Azure Key Vault для хранения секрета.
• Добавьте строку подключения в качестве секрета в концентратор событий.
• Чтобы получить доступ к секрету, добавьте политику доступа для Microsoft Graph.

Шаги:

1. Откройте портал Azure в браузере.
2. Выберите Создать ресурс.
3. В строке поиска введите Хранилище ключей.
4. Выберите хранилище ключей из предложенных. Будет загружена страница создания хранилища ключей.
5. На странице создания хранилища ключей нажмите Создать.
6. Заполните сведения для создания хранилища ключей и щелкните Проверка + создание, затем Создать.
7. Перейдите к только что созданному хранилищу ключей, выбрав Перейти к ресурсу в уведомлении.
8. Скопируйте DNS-имя. Это потребуется для следующего шага.
9. Перейдите в Секреты и выберите + Создать/импортировать.
10. Введите название секрета и сохраните его для следующего этапа. В качестве значения используйте строку подключения, созданную на этапе для концентратора событий. Нажмите Создать.
11. Щелкните Политики доступа, затем + Добавить политику доступа.
12. Чтобы открыть Разрешения секретов, выберите Получить, затем Выбрать первичный, а затем Отслеживание изменений в Microsoft Graph. Нажмите Добавить.

Создание подписки и просмотр уведомлений

После создания обязательных служб хранилища Azure Key Vault и концентраторов событий Azure вы сможете создать свою подписку и начать получать уведомления об изменениях через концентраторы событий Azure.

Создание подписки

Подписки на изменение уведомлений с помощью концентраторов событий почти идентичны уведомлениям об изменениях с помощью веб-перехватчиков. Основное отличие заключается в том, что для доставки уведомлений используют концентраторы событий. Другие операции сходны, в том числе создание подписки.

Основное отличие в ходе создания подписки будет заключаться в значении notificationUrl,. Необходимо настроить его на EventHub:https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname> со следующими значениями:

• azurekeyvaultname — название созданного хранилища ключей. Его можно найти в DNS-имени.
• secretname — название созданного секрета. Его можно найти на странице Секреты в хранилище Azure Key Vault.
• domainname — имя клиента, например, consto.onmicrosoft.com или contoso.com. Поскольку этот домен будет использоваться для доступа к хранилищу Azure Key Vault, важно, чтобы он соответствовал домену, используемому подпиской Azure с хранилищем Azure Key Vault. Чтобы получить эту информацию, вы можете перейти на страницу обзора созданного хранилища Azure Key Vault и щелкнуть на подписку. Имя домена выводится в поле Каталог.

Получение уведомлений

События будут доставлены концентраторами событий в ваше приложение. Дополнительные сведения см. в статье Получение событий в документации по концентраторам событий.

Чтобы вы могли получать уведомления в приложении, потребуется создать еще одну политику общего доступа с разрешением на "Прослушивание" и получить строку подключения, как в инструкциях из раздела Настройка концентратора событий Azure.

Примечание. Создайте отдельную политику для приложения, которое прослушивает сообщения в концентраторах событий, вместо того чтобы повторно использовать строку подключения, заданную в хранилище Azure KeyVault. Это гарантирует, что каждый компонент решения будет иметь только нужные разрешения в соответствии с принципом минимальных разрешений.

Примечание. Ваше приложение будет получать сообщения о проверке каждый раз при создании новой подписки. Эти уведомления следует пропустить. В приведенном ниже примере представлен текст сообщения о проверке.

 {
    "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"
            }
        }
    ]
}

Что произойдет, если приложение для отслеживания изменений в Microsoft Graph отсутствует?

Возможно, в вашем клиенте нет субъекта-службы отслеживания изменений в Microsoft Graph. Это зависит от того, когда был создан клиент и от административных операций. Чтобы устранить эту проблему, выполните следующий запрос в проводнике Microsoft Graph.

Сведения о запросе: 0bf30f3b-4a52-48df-9a82-234910c4a086 — глобальный идентификатор приложения для отслеживания изменений в Microsoft Graph.

HTTP

POST https://graph.microsoft.com/v1.0/servicePrincipals

{
    "appId": "0bf30f3b-4a52-48df-9a82-234910c4a086"
}

C#

// Code snippets are only available for the latest version. Current version is 5.x

var graphClient = new GraphServiceClient(requestAdapter);

var requestBody = new ServicePrincipal
{
	AppId = "0bf30f3b-4a52-48df-9a82-234910c4a086",
};
var result = await graphClient.ServicePrincipals.PostAsync(requestBody);

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Go

import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphmodels "github.com/microsoftgraph/msgraph-sdk-go/models"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


requestBody := graphmodels.NewServicePrincipal()
appId := "0bf30f3b-4a52-48df-9a82-234910c4a086"
requestBody.SetAppId(&appId) 

result, err := graphClient.ServicePrincipals().Post(context.Background(), requestBody, nil)

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.appId = "0bf30f3b-4a52-48df-9a82-234910c4a086";

graphClient.servicePrincipals()
	.buildRequest()
	.post(servicePrincipal);

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

const servicePrincipal = {
    appId: '0bf30f3b-4a52-48df-9a82-234910c4a086'
};

await client.api('/servicePrincipals')
	.post(servicePrincipal);

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

PHP

<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestBody = new ServicePrincipal();
$requestBody->setAppId('0bf30f3b-4a52-48df-9a82-234910c4a086');



$result = $graphServiceClient->servicePrincipals()->post($requestBody);

Дополнительные сведения о добавлении пакета SDK в проект и создании экземпляра authProvider см. в документации по пакету SDK.

Примечание. Вы можете получить отказ в выполнении этого запроса. В этом случае щелкните значок шестеренки рядом с именем своей учетной записи в левом верхнем углу. Затем выберите Выбрать разрешения, а затем выполните поиск по запросу Application.ReadWrite.All. Проверьте разрешения и выберите Согласие. После того как вы подтвердите новое разрешение, снова выполните поисковый запрос.

Примечание. Этот API-интерфейс действует только для учебной или рабочей учетной записи, но не в личной учетной записи. Убедитесь, что вы вошли в систему через учетную запись в своем домене.

Кроме того, для добавления отсутствующего субъекта-службы можно использовать командлет PowerShell New-MgServicePrincipal в Microsoft Graph. Ниже приведен пример сценария.

Connect-Graph -Scopes "Application.ReadWrite.All"
New-MgServicePrincipal -AppId "0bf30f3b-4a52-48df-9a82-234910c4a086"

Дальнейшие действия

См. следующие краткие руководства о концентраторах событий Azure:

• .NET Core
• Java
• Python
• JavaScript