さまざまな方法で変更通知を受け取る (プレビュー)Get change notifications delivered in different ways (preview)

変更通知は、さまざまな方法でサブスクライバーに配信できます。Change notifications can be delivered in different ways to subscribers. 変更通知の主な配信モードが Webhook を使用する場合、高スループット シナリオや受信者が公開されている通知 URL を公開できない場合に Webhook を利用することは困難です。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.

この変更通知の配信モードは、Microsoft Graph の変更通知をサポートするすべてのリソースで使用できます。This change notifications delivery mode is available for all resources that support Microsoft Graph change notifications.

高スループット シナリオの好例としては、大量のリソースをサブスクライブするアプリケーション、高頻度で変化するリソースをサブスクライブするアプリケーション、および大規模な組織全体のリソースをサブスクライブするマルチ テナント アプリケーションがあります。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.

Azure Event Hubs を使用した変更通知の受け取りUsing Azure Event Hubs to receive change notifications

Azure Event Hubs は、一般的なリアルタイム イベントの取り込みと配布サービスであり、規模に合わせて構築されています。Azure Event Hubs is a popular real-time events ingestion and distribution service built for scale. 従来の Webhook の代わりに Azure Event Hubs を使用して変更通知を受け取ることができます。You can use Azure Events Hubs instead of traditional webhooks to receive change notifications. この機能は現在プレビューの段階です。This feature is currently in preview.
変更通知の受け取りに Azure Event Hub を使用する方法は、次のような点で Webhook とは異なります。Using Azure Event Hubs to receive change notifications differs from webhooks in a few ways, including:

  • 公開されている通知 URL には依存しません。You don't rely on publicly exposed notification URLs. Event Hubs SDK は、通知をアプリケーションにリレーします。The Event Hubs SDK will relay the notifications to your application.
  • 通知 URL の検証に返信する必要はありません。You don't need to reply to the notification URL validation. 受信した検証メッセージは無視してかまいません。You can ignore the validation message that you receive.
  • Azure イベント ハブを用意する必要があります。You'll need to provision an Azure Event Hub.
  • Azure Key Vault をプロビジョニングする必要があります。You'll need to provision an Azure Key Vault.

Azure KeyVault および Azure イベント ハブの設定Set up the Azure KeyVault and Azure Event Hubs

このセクションでは、必要な Azure サービスのセットアップについて説明します。This section will walk you through the setup of required Azure services.

オプション 1: Azure CLI の使用Option 1: Using the Azure CLI

Azure CLI を使用すると、Azure で管理タスクをスクリプト化して自動化することができます。The Azure CLI allows you to script and automate adminstrative tasks in Azure. CLI は、ローカル コンピューターにインストールされているか、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}"

注: ここで提供されるスクリプトは、Linux ベースのシェル、Windows WSL と Azure Cloud Shell と互換性があります。Note: The script provided here is compatible with Linux based shells, Windows WSL, and Azure Cloud Shell. Windows シェルで実行するには、いくつかの更新が必要です。It will require some updates to run in Windows shells.

オプション 2: Azure Portal の使用Option 2: Using the Azure Portal

Azure Event Hubs の構成Configuring the Azure Event Hub

このセクションでは、次のことを行います。In this section you will:

  • Azure イベント ハブの名前空間を作成します。Create an Azure Event Hub namespace.
  • 通知をリレーして配信するハブをその名前空間に追加します。Add a hub to that namespace that will relay and deliver notifications.
  • 新しく作成されたハブに接続文字列を取得できる共有アクセス ポリシーを追加します。Add a shared access policy that will allow you to get a connection string to the newly created hub.

手順:Steps:

  1. Azure Portal のブラウザーを開きます。Open a browser to the Azure Portal.
  2. [リソースの作成] を選択します。Select Create a resource.
  3. 検索バーに Event Hubs を入力します。Type Event Hubs in the search bar.
  4. Event Hubs 提案を選択します。Select the Event Hubs suggestion. Event Hubs の作成ページが読み込まれます。The Event Hubs creation page will load.
  5. Event Hubs の作成ページで、[作成] をクリックします。On the Event Hubs creation page, click Create.
  6. Event Hubs 名前空間の作成の詳細を入力して、[作成] をクリックします。Fill in the Event Hubs namespace creation details, and then click Create.
  7. Event Hubs 名前空間がプロビジョニングされたら、名前空間のページに移動します。When the Event Hub namespace is provisioned, go to the page for the namespace.
  8. [Event Hub][+ Event Hub] をクリックします。Click Event Hubs and + Event Hub.
  9. 新しい Event Hub に名前を付けて、[作成] をクリックします。Give a name to the new Event Hub, and click Create.
  10. Event Hub を作成した後、Event Hub の名前をクリックして、[共有アクセス ポリシー][+ 追加] をクリックして、新しいポリシーを追加します。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. ポリシーに名前を付けて、[送信] を選択して、[作成] をクリックします。Give a name to the policy, check Send, and click Create.
  12. ポリシーを作成した後、ポリシーの名前をクリックして、詳細パネルを開き、接続文字列 - 主キーの値をコピーします。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. この情報は、次の手順で必要になりますので、書き留めてください。Write it down; you'll need it for the next step.
Azure Key Vault の構成Configuring the Azure Key Vault

イベント ハブに安全にアクセスし、キーの回転を許可するために、Microsoft Graph は 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.
このセクションでは、次のことを行います。In this section, you will:

  • シークレットを保存する Azure Key Vault を作成します。Create an Azure Key Vault to store secret.
  • 接続文字列をシークレットとしてイベント ハブに追加します。Add the connection string to the Event Hub as a secret.
  • Microsoft Graph がシークレットにアクセスするためのアクセス ポリシーを追加します。Add an access policy for Microsoft Graph to access the secret.

手順:Steps:

  1. Azure Portal のブラウザーを開きます。Open a browser to the Azure Portal.
  2. [リソースの作成] を選択します。Select Create a resource.
  3. 検索バーに Key Vault を入力します。Type Key Vault in the search bar.
  4. Key Vault 提案を選択します。Select the Key Vault suggestion. Key Vault の作成ページが読み込まれます。The Key Vault creation page will load.
  5. Key Vault の作成ページで、[作成] をクリックします。On the Key Vault creation page, click Create.
  6. Key Vault の作成の詳細を入力して、[確認 + 作成][作成] をクリックします。Fill in the Key Vault creation details, and then click Review + Create and Create.
  7. 通知で [リソースに移動] を使用して、新しく作成されたキーのキー コンテナーに移動します。Go to the newly crated key vault using the Go to resource from the notification.
  8. DNS 名をコピーします。次の手順で必要になります。Copy the DNS name; you will need it for the next step.
  9. [シークレット] に移動して、[+ 生成/インポート] をクリックします。Go to Secrets and click + Generate/Import.
  10. シークレットに名前を付けて、後で使用するために名前を書き留めます。次の手順で必要になります。Give a name to the secret, and keep the name for later; you will need it for the next step. 値として、Event Hubs 手順で生成した接続文字列を貼り付けます。For the value, paste in the connection string you generated at the Event Hubs step. [作成] をクリックします。Click Create.
  11. [アクセス ポリシー][+ アクセス ポリシーの追加] をクリックします。Click Access Policies and + Add Access Policy.
  12. [シークレットのアクセス許可] 場合、[取得] を選択し、[プリンシパルを選択] の場合、[Microsoft Graph の変更追跡] を選択します。For Secret permissions, select Get, and for Select Principal, select Microsoft Graph Change Tracking. [追加] をクリックします。Click Add.

サブスクリプションの作成と通知の受け取りCreating the subscription and receiving notifications

必要な Azure KeyVault および Azure Event Hubs サービスを作成すると、サブスクリプションを作成し、Azure Event Hubs を介して変更通知を受け取ることができます。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.

サブスクリプションの作成Creating the subcription

Event Hubs を使用した変更通知のサブスクリプションは、Webhook を使用した変更通知とほぼ同じです。Subscriptions to change notifications with Event Hubs are almost identical to change notifications with webhooks. 主な違いは、通知の配信を Event Hubs に依存していることです。The key difference is that they rely on Event Hubs to deliver notifications. サブスクリプションの作成を含む他のすべての作業が似ています。All other operations are similar, including subscription creation.

サブスクリプションを作成するときの主な違いは、notificationUrl です。The main difference during subscription creation will be the notificationUrl. 次の値を使用して、この値を EventHub:https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname> に設定する必要があります。You must set it to EventHub:https://<azurekeyvaultname>.vault.azure.net/secrets/<secretname>?tenantId=<domainname>, with the following values:

  • azurekeyvaultname - キー コンテナーを作成したときに付けた名前。azurekeyvaultname - The name you gave to the key vault when you created it. DNS 名で見つけることができます。Can be found in the DNS name.
  • secretname - シークレットを作成したときに付けた名前。secretname - The name you gave to the secret when you created it. Azure Key Vault の [シークレット] ページで見つけることができます。Can be found on the Azure Key Vault Secrets page.
  • domainname - テナントの名前 (例: consto.onmicrosoft.com または contoso.com)。domainname - The name of your tenant; for example, consto.onmicrosoft.com or contoso.com. このドメインは Azure Key Vault へのアクセスに使用されるため、Azure Key Vault を保持する Azure サブスクリプションで使用されるドメインと一致することが重要です。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. この情報を取得するには、作成した Azure Key Vault の概要ページに移動し、サブスクリプションをクリックします。To get this information, you can go to the overview page of the Azure Key Vault you created and click the subscription. ドメイン名がディレクトリ フィールドの下に表示されます。The domain name is displayed under the Directory field.

通知の受け取りReceiving notifications

イベントは、Event Hubs によってアプリケーションに配信されます。Events will be now delivered to your application by Event Hubs. 詳細については、Event Hubs ドキュメントで「イベントの受け取り」を参照してください。For details, see receiving events in the Event Hubs documentation.

アプリケーションで通知を受け取るには、まず、「Azure イベント ハブの構成」に記載されている手順のように、「待ち受け」権限を持つ他の共有アクセス ポリシーを作成し、接続文字列を取得する必要があります。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.

注意: Azure KeyVault で設定したものと同じ接続文字列を再利用する代わりに、Event Hubs のメッセージを待ち受けるアプリケーションの別のポリシーを作成します。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. これにより、ソリューションの各コンポーネントは、必要なアクセス許可のみを持ち、最小限のアクセス許可のセキュリティ プリンシパルに従います。This ensures that each component of the solution has only the permissions it needs and follows the least permissions security principle.

注: アプリケーションは、新しいサブスクリプションが作成されるたびに検証メッセージを受け取ります。Note: Your application receives validation messages whenever it creates a new subscription. これらの通知は無視してください。You should ignore these notifications. 次の例は、検証メッセージの本文を表します。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"
            }
        }
    ]
}

Microsoft Graph の変更追跡アプリケーションがない場合はどうなりますか?What happens if the Microsoft Graph change tracking application is missing?

テナントが作成された時期と管理作業によっては、Microsoft Graph の変更追跡サービス プリンシパルがテナントにない可能性があります。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. この問題を解決するには、Microsoft Graph Explorer次のクエリを実行します。To resolve this issue, run the following query in Microsoft Graph Explorer.

クエリの詳細:Query details:

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

注意: このクエリを実行すると、アクセスが拒否されます。Note: You can get an access denied running this query. この場合、左上のアカウント名の横にある歯車アイコンを選択します。In this case, select the gear icon next to your account name in the top left corner. 次に、[アクセス許可の選択] を選択して、Application.ReadWrite.All を検索します。Then select Select Permissions and search for Application.ReadWrite.All. アクセス許可を確認して、[同意] を選択します。Check the permission and select Consent. この新しいアクセス許可に同意した後、要求を再実行します。After consenting to this new permission, run the request again.

注意: この API は、個人アカウントではなく、学校または職場のアカウントでのみ動作します。Note: This API only works with a school or work account, not with a personal account. ドメインのアカウントでサインインしていることを確認します。Make sure that you are signed in with an account on your domain.

またはこの Azure Active Directory PowerShell スクリプトを使用して不足しているサービス プリンシパルを追加することができます。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

次の手順Next steps

次の Azure Event Hubs クイック スタートをご覧ください。See the following Azure Event Hubs quick starts: