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

Статья
10/14/2024

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

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

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

Важно!

Проверка подлинности Центров событий с помощью подписанных URL-адресов (SAS) будет нерекомендуемой в будущем. Мы рекомендуем проверить подлинность Центров событий с помощью Microsoft Entra ID управления доступом на основе ролей (RBAC).

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

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

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

Настройка проверки подлинности Центры событий Azure

Центры событий Azure поддерживает проверку подлинности с помощью подписанных URL-адресов (SAS) или Microsoft Entra ID управления доступом на основе ролей (RBAC). Дополнительные сведения см. в статье Авторизация доступа к Центры событий Azure.

В этом разделе показано, как настроить проверку подлинности Центры событий Azure с помощью Microsoft Entra ID управления доступом на основе ролей (RBAC) на портал Azure.

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

Войдите в портал Azure с правами на создание ресурсов в подписке Azure.
Выберите Создать ресурс, введите Центры событий в строке поиска, а затем выберите предложение Центры событий .
На странице Создание Центров событий выберите Создать.
Введите сведения о создании пространства имен Центров событий и нажмите кнопку Создать.
После подготовки пространства имен Центров событий перейдите на страницу пространства имен.
Выберите Центры событий , а затем + Концентратор событий.
Присвойте имя новому концентратору событий и нажмите кнопку Создать.
После создания концентратора событий перейдите в пространство имен Центров событий и выберите контроль доступа (IAM) на боковой панели.
Выберите Назначения ролей.
Выберите + Добавить и добавить назначение ролей.
В разделе Роль перейдите в раздел Роли функции задания, выберите Центры событий Azure Отправителя данных, а затем нажмите кнопку Далее.
На вкладке Участники выберите Назначить доступ пользователю, группе или субъекту-службе.
Выберите + Выбрать участников, а затем найдите и выберите Microsoft Graph Отслеживание изменений.
Выберите Проверить и назначить , чтобы завершить процесс.

В этом разделе показано, как настроить проверку подлинности Центры событий Azure с помощью подписанных URL-адресов (SAS) через Azure CLI.

Azure CLI позволяет создавать скрипты и автоматизировать задачи администрирования в Azure. Средство CLI можно установить на локальный компьютер или запустить напрямую в Azure Cloud Shell.

Важно!

Проверка подлинности Центров событий с помощью подписанных URL-адресов (SAS) будет нерекомендуемой в будущем. Вместо этого рекомендуется использовать Microsoft Entra ID управление доступом на основе ролей (RBAC). Следуйте инструкциям по переходу на RBAC.

# --------------
# 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}"

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

После создания необходимых служб Azure KeyVault и Центры событий Azure вы можете создать подписку на уведомления об изменениях и начать получать уведомления об изменениях через Центры событий Azure.

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

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

При создании подписки notificationUrl должен указывать на расположение Центров событий.

Использование RBAC
Использование Key Vault

Если вы используете управление доступом на основе ролей, свойство notificationUrl выглядит следующим образом:

EventHub:https://<eventhubnamespace>.servicebus.windows.net/eventhubname/<eventhubname>?tenantId=<domainname>

<eventhubnamespace> — это имя, присвоенное пространству имен Центров событий. Его можно найти на странице Обзор Центров событий в разделе Имя узла.
<eventhubname> — это имя, присвоенное концентратору событий. Его можно найти в разделе Центры событий —> обзор —> Центры событий.
<domainname> — это имя вашего клиента; например, contoso.com. Так как этот домен используется для доступа к Центры событий Azure, важно, чтобы он соответствовал домену, используемому подпиской Azure, которая содержит Центры событий Azure. Чтобы получить эти сведения, выберите меню Microsoft Entra ID на портал Azure и проверка страницу Обзор. Доменное имя отображается в основном домене.

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

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

Примечание.

Дублирование подписок запрещено. Если запрос подписки содержит те же значения для changeType и ресурса , что и в существующей подписке, запрос завершается ошибкой с кодом 409 ConflictHTTP и сообщением Subscription Id <> already exists for the requested combinationоб ошибке .

Перенос проверки подлинности концентратора событий в Microsoft Entra ID RBAC

В этом разделе описано, как перенести существующие Центры событий с проверкой подлинности SAS в Microsoft Entra ID проверки подлинности RBAC. Используйте то же пространство имен концентратора событий, которое использовалось при проверке подлинности SAS с помощью Azure CLI или портал Azure.

В том же пространстве имен концентратора событий, которое используется для существующей подписки, создайте концентратор событий.
Создайте новую подписку с теми же сведениями, что и существующая, за исключением использования имени нового концентратора событий из предыдущего шага в URL-адресе. Дополнительные сведения см. в разделе Создание подписки: использование RBAC.

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

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

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

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

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

Совет

Создайте отдельную политику для приложения, которое прослушивает сообщения Центров событий вместо того, чтобы повторно использовать тот же строка подключения, заданный в 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"
            }
        }
    ]
}

Подписки на расширенные уведомления с большими полезными данными

Максимальный размер сообщений для Центров событий составляет 1 МБ. При использовании расширенных уведомлений могут потребоваться уведомления, превышающие это ограничение. Чтобы получать уведомления размером более 1 МБ через Центры событий, необходимо также добавить учетную запись хранения BLOB-объектов в запрос подписки.

Настройка хранилища и создание подписки

Создайте учетную запись хранения.
Создайте контейнер в учетной записи хранения. Имя контейнера должно иметь значение microsoft-graph-change-notifications.
Получите ключи доступа к учетной записи хранения или строка подключения.
Добавьте строка подключения в хранилище ключей и присвойте ему имя. Это значение является именем секрета.
Создайте или повторно создайте подписку, включив свойство blobStoreUrl в следующем синтаксисе: blobStoreUrl: "https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>"

Получение расширенных уведомлений

Когда Центры событий получают полезные данные уведомления размером более 1 МБ, уведомление не содержит свойств resource, resourceData и encryptedContent , включенных в расширенные уведомления. Вместо этого уведомление содержит дополнительное свойствоPayloadStorageId с идентификатором, указывающим на большой двоичный объект в учетной записи хранения, где хранятся эти свойства.

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

Субъект-служба Microsoft Graph Отслеживание изменений может отсутствовать в клиенте в зависимости от времени создания клиента и административных операций. Глобальный уникальный идентификатор appId субъекта-службы — это 0bf30f3b-4a52-48df-9a82-234910c4a086 , и вы можете выполнить следующий запрос, чтобы убедиться, что он существует в клиенте.

GET https://graph.microsoft.com/v1.0/servicePrincipals(appId='0bf30f3b-4a52-48df-9a82-234910c4a086')


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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipalsWithAppId("{appId}").GetAsync();



mgc service-principals-with-app-id get --app-id {app-id}



// Code snippets are only available for the latest major version. Current major version is $v1.*

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


// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
appId := "{appId}"
servicePrincipals, err := graphClient.ServicePrincipalsWithAppId(&appId).Get(context.Background(), nil)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ServicePrincipal result = graphClient.servicePrincipalsWithAppId("{appId}").get();

Snippet not available


<?php
use Microsoft\Graph\GraphServiceClient;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);


$result = $graphServiceClient->servicePrincipalsWithAppId('{appId}', )->get()->wait();


Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalByAppId


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python

result = await graph_client.service_principals_with_app_id("{appId}").get()

Если субъект-служба не существует, создайте его следующим образом. Для выполнения этой операции вызывающему приложению необходимо предоставить разрешение Application.ReadWrite.All .

Метод 1

POST https://graph.microsoft.com/v1.0/servicePrincipals
Content-type: application/json

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


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

// Dependencies
using Microsoft.Graph.Models;

var requestBody = new ServicePrincipal
{
	AppId = "0bf30f3b-4a52-48df-9a82-234910c4a086",
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.ServicePrincipals.PostAsync(requestBody);



mgc service-principals create --body '{\
    "appId": "0bf30f3b-4a52-48df-9a82-234910c4a086"\
}\
'



// Code snippets are only available for the latest major version. Current major version is $v1.*

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

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

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
servicePrincipals, err := graphClient.ServicePrincipals().Post(context.Background(), requestBody, nil)


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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

ServicePrincipal servicePrincipal = new ServicePrincipal();
servicePrincipal.setAppId("0bf30f3b-4a52-48df-9a82-234910c4a086");
ServicePrincipal result = graphClient.servicePrincipals().post(servicePrincipal);


const options = {
	authProvider,
};

const client = Client.init(options);

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

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


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\Models\ServicePrincipal;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

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

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


Import-Module Microsoft.Graph.Applications

$params = @{
	appId = "0bf30f3b-4a52-48df-9a82-234910c4a086"
}

New-MgServicePrincipal -BodyParameter $params


# Code snippets are only available for the latest version. Current version is 1.x
from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = ServicePrincipal(
	app_id = "0bf30f3b-4a52-48df-9a82-234910c4a086",
)

result = await graph_client.service_principals.post(request_body)

Метод 2

POST https://graph.microsoft.com/v1.0/servicePrincipals(appId='0bf30f3b-4a52-48df-9a82-234910c4a086')
Content-type: application/json
Prefer: create-if-missing

{
    "displayName": "Microsoft Graph Change Tracking"
}

Общие сведения об уведомлениях об изменениях
См. следующие краткие руководства о концентраторах событий Azure:
- .NET Core
- Java
- Python
- JavaScript

Поделиться через

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

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

Настройка проверки подлинности Центры событий Azure

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

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

Настройка Key Vault Azure

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

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

Перенос проверки подлинности концентратора событий в Microsoft Entra ID RBAC

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

Обработка уведомлений о проверке

Подписки на расширенные уведомления с большими полезными данными

Настройка хранилища и создание подписки

Получение расширенных уведомлений

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

Обратная связь

Дополнительные ресурсы

Поделиться через

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

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

Настройка проверки подлинности Центры событий Azure

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

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

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

Перенос проверки подлинности концентратора событий в Microsoft Entra ID RBAC

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

Обработка уведомлений о проверке

Подписки на расширенные уведомления с большими полезными данными

Настройка хранилища и создание подписки

Получение расширенных уведомлений

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

Связанные материалы

Обратная связь

Дополнительные ресурсы