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

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

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

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

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

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

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

Настройка проверки подлинности Центры событий 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

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

В этом разделе вы:

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

Шаги:

1. Войдите в портал Azure с правами на создание ресурсов в подписке Azure.
2. Выберите Create тип ресурса>Центры событий в строке > поиска выберите предложение Центры событий.
3. На странице создания Центров событий выберите Create.
4. Введите сведения о создании пространства имен Центров событий и выберите Create.
5. После подготовки пространства имен концентратора событий перейдите на страницу пространства имен.
6. Выберите Центры событий и + Концентратор событий.
7. Присвойте имя новому концентратору событий и выберите Create.
8. После создания концентратора событий выберите имя концентратора событий, а затем выберите Политики общего доступа и + Добавить , чтобы добавить новую политику.
9. Укажите имя политики, проверка Отправить и выберите Create.
10. После создания политики выберите имя политики, чтобы открыть панель сведений, а затем скопируйте значение строки подключения— первичный ключ . Запишите значение; он вам понадобится для следующего шага.

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

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

В этом разделе вы:

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

Шаги:

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

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

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

В этом разделе вы:

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

Шаги:

1. Войдите в портал Azure с правами на создание ресурсов в подписке Azure.
2. Выберите Create тип ресурса>Центры событий в строке > поиска выберите предложение Центры событий.
3. На странице создания Центров событий выберите Create.
4. Введите сведения о создании пространства имен Центров событий и выберите Create.
5. После подготовки пространства имен концентратора событий перейдите на страницу пространства имен.
6. Выберите Центры событий и + Концентратор событий.
7. Присвойте имя новому концентратору событий и выберите Create.
8. После создания концентратора событий выберите имя концентратора событий, а затем выберите контроль доступа (IAM) на боковой панели.
9. Выберите Назначения ролей.
10. Выберите + Добавить и добавить назначение ролей.
11. В разделе Роли>функции задания роли выберите Центры событий Azure >Отправитель> данных нажмите кнопку Далее.
12. На вкладке Участники выберите Назначить доступ пользователю, группе или субъекту-службе.
13. Выберите + Выберите участников>, выполните поиск и выберите Microsoft Graph Отслеживание изменений.
14. Выберите Проверить и назначить , чтобы завершить процесс.

Create подписку и получать уведомления

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

Create подписки

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

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

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

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

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

Примечание.

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

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

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

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

Совет

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

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

1. Create учетной записи хранения.
2. Create контейнер в учетной записи хранения и назначьте ему имя.
3. Получите ключи доступа к учетной записи хранения или строка подключения.
4. Добавьте строка подключения в хранилище ключей и присвойте ему имя. Это значение является именем секрета.
5. Create или повторно создайте подписку, добавив свойство 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 , и вы можете выполнить следующий запрос, чтобы убедиться, что он существует в клиенте.

HTTP

GET 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

// 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();

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

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc service-principals-with-app-id get --app-id {app-id}

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

Go

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

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



appId := "{appId}"
servicePrincipals, err := graphClient.ServicePrincipalsWithAppId(&appId).Get(context.Background(), nil)

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

Java

// 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();

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

JavaScript

Snippet not available

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

PHP

<?php
use Microsoft\Graph\GraphServiceClient;


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


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

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

PowerShell

Import-Module Microsoft.Graph.Applications

Get-MgServicePrincipalByAppId

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

Python

from msgraph import GraphServiceClient

graph_client = GraphServiceClient(credentials, scopes)


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

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

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

Метод 1

HTTP

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

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

C#

// 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);

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

CLI

// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc service-principals create --body '{\
    "appId": "0bf30f3b-4a52-48df-9a82-234910c4a086"\
}\
'

Дополнительные сведения о добавлении пакета 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) 

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

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

Java

// 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);

Дополнительные сведения о добавлении пакета 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
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();

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

PowerShell

Import-Module Microsoft.Graph.Applications

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

New-MgServicePrincipal -BodyParameter $params

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

Python

from msgraph import GraphServiceClient
from msgraph.generated.models.service_principal import ServicePrincipal

graph_client = GraphServiceClient(credentials, scopes)

request_body = ServicePrincipal(
	app_id = "0bf30f3b-4a52-48df-9a82-234910c4a086",
)

result = await graph_client.service_principals.post(request_body)

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

Метод 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