サブスクリプションを作成する

名前空間: microsoft.graph

変更の要求された種類が Microsoft Graph の指定されたリソースに発生したときに変更通知を受信するため、リスナー アプリケーションに登録します。

サブスクリプションを作成できるリソースとサブスクリプションの制限事項を特定するには、「 リソース データの変更に関する通知の設定: サポートされているリソース」を参照してください。

一部のリソースは、リッチ通知、つまりリソース データを含む通知をサポートします。 これらのリソースの詳細については、「 リソース データを含む変更通知のセットアップ: サポートされるリソース」を参照してください。

この API は、次の国内クラウド展開で使用できます。

アクセス許可

サブスクリプションを作成するには、リソースに対する読み取りアクセス許可が必要です。 たとえば、メッセージの変更通知を受け取るには、アプリに Mail.Read アクセス許可が必要です。

要求されたリソースとアクセス許可の種類 (委任およびアプリケーション) によっては、以下の表で指定されているアクセス許可がこの API を呼び出すために最小限必要な特権となります。 より多くの特権アクセス許可を選択する前に 注意する ことを含め、詳細については、[アクセス許可] で次のアクセス許可を検索してください。

chatMessage

リソース データを含めるように chatMessage サブスクリプションを指定することもできます (includeResourceData を true に設定)。 その場合、暗号化が必要であり、そのようなサブスクリプションに encryptionCertificate が指定されていないと、サブスクリプションの作成は失敗します。

Prefer: include-unknown-enum-members 要求ヘッダーを使用して、chatMessage messageTypeのエボルベブル列挙型で次の値を取得します。 /teams/{id}/channels/{id}/messages および /chats/{id}/messages リソースのsystemEventMessage。

conversationMember

リソース データを含めるように conversationMember サブスクリプションを指定することができます (includeResourceData を true に設定)。 その場合、暗号化が必要であり、そのようなサブスクリプションに encryptionCertificate が指定されていないと、サブスクリプションの作成は失敗します。

チーム、チャネル、チャット

チーム、 チャネル、 チャット のサブスクリプションにリソース データを含めるように指定できます (includeResourceData を true に設定)。 その場合、暗号化が必要であり、そのようなサブスクリプションに encryptionCertificate が指定されていないと、サブスクリプションの作成は失敗します。

notifyOnUserSpecificProperties クエリ文字列パラメーターは、特定のチャットまたはユーザー レベルで変更をサブスクライブするときに使用できます。 サブスクリプションの作成時にクエリ文字列パラメーター notifyOnUserSpecificProperties を true に設定すると、2 種類のペイロードがサブスクライバーに送信されます。 1 つのタイプにはユーザー固有のプロパティが含まれており、もう 1 つはユーザー固有のプロパティなしで送信されます。 詳細については、「 Microsoft Graph を使用してチャットの変更通知を取得する」を参照してください。

aiInsights

Copilot AI 分析情報のサブスクリプションには、次の Copilot サービス プランを含む有効な Copilot ライセンスが必要です:

• Microsoft 365 Copilot Chat: 3f30311c-6b1e-48a4-ab79-725b469da960

aiInteraction

Copilot AI 対話のサブスクリプションには、次の Copilot サービス プランを含む有効な Copilot ライセンスが必要です:

• Microsoft 365 Copilot Chat: 3f30311c-6b1e-48a4-ab79-725b469da960

特定のユーザーが参加している Copilot AI 対話を対象とするサブスクリプションの場合、リソース パス内のユーザーには、有効な状態で以前のサービス プランが割り当てられている必要があります。

テナント全体の Copilot AI 対話を対象とするサブスクリプションの場合、テナントには、以前のすべての Copilot サービス プランを含む有効なライセンスがプロビジョニングされている必要があります。

driveItem

OneDrive アイテムのサブスクリプションには、さらに多くの制限が適用されます。 この制限は、サブスクリプションの作成および管理 (取得、更新、削除) に適用されます。

個人用 OneDrive では、そのドライブのルート フォルダーまたは任意のサブフォルダーにサブスクライブできます。 職場または学校の OneDrive では、ルート フォルダーのみを購読できます。 サブスクライブしたフォルダー、またはその階層内のファイル、フォルダー、またはその他の driveItem インスタンスで要求された変更に対して、変更通知が送信されます。 個々のファイルなど、フォルダーではない drive または driveItem インスタンスをサブスクライブすることはできません。

職場または学校用 OneDrive と SharePoint は、 driveItem で発生したセキュリティ イベントのアプリケーション通知を送信するサポートをサポートします。 これらのイベントをサブスクライブするには、prefer:includesecuritywebhooks ヘッダーを要求に追加してサブスクリプションを作成します。 サブスクリプションが作成された後、アイテムに対するアクセス許可が変更されたときに通知を受け取ります。 このヘッダーは、職場または学校の SharePoint と OneDrive に適用されますが、コンシューマーの OneDrive アカウントには適用されません。

連絡先、イベント、メッセージ

Outlook の連絡先、 イベント、 またはメッセージ リソースの変更をサブスクライブし、必要に応じて、暗号化されたリソース データを通知に含めるかどうかを POST 要求のペイロードで指定できます。

サブスクリプションの作成と管理 (取得、更新、および削除) には、リソースの読み取りスコープが必要です。 たとえば、メッセージに関する変更通知を受信するには、アプリに Mail.Read アクセス許可が必要です。 Outlook 変更通知は、委任されたアクセス許可スコープとアプリケーション アクセス許可スコープをサポートします。 次の制限がある点に注意してください。

• 委任されたアクセス許可では、サインインしているユーザーのメールボックス内のフォルダーにあるアイテムのみをサブスクライブできます。 たとえば、委任されたアクセス許可 Calendars.Read を使用して、別のユーザーのメールボックス内のイベントをサブスクライブすることはできません。

• 共有または委任フォルダーの Outlook 連絡先、イベント、メッセージの変更通知をサブスクライブするには、次のようにします。

  • 対応するアプリケーション アクセス許可を使用して、テナントの任意のユーザーのフォルダーまたはメールボックス内にあるアイテムの変更をサブスクライブします。
  • Outlook の共有アクセス許可 (Contacts.Read.Shared、Calendars.Read.Shared、Mail.Read.Shared、およびそれに相当する読み取り/書き込みアクセス許可) は、共有フォルダーまたは委任フォルダー内のアイテムの変更通知のサブスクライブをサポートし ていない ため、使用しないでください。

onlineMeetings, プレゼンス

onlineMeetings とプレゼンスのサブスクリプションでは、暗号化されたリソース データを含む通知のサブスクリプションを作成するときに、encryptionCertificate プロパティと encryptionCertificateId プロパティが必要です。 詳細については、「 リソース データを含めるように変更通知を設定する」を参照してください。 オンライン会議のサブスクリプションの詳細については、「 オンライン会議の変更通知を受け取る」を参照してください。

virtualEventWebinar と virtualEventTownhall

仮想イベントのサブスクリプションは、基本的な通知のみをサポートし、仮想イベントの少数のエンティティに制限されます。 サポートされているサブスクリプションの種類の詳細については、「 Microsoft Teams 仮想イベント更新プログラムの変更通知の取得」を参照してください。

HTTP 要求

POST /subscriptions

要求ヘッダー

要求本文

要求本文で、subscription オブジェクトの JSON 表記を指定します。

応答

成功した場合、このメソッドは 201 Created 応答コードと応答本文の サブスクリプション オブジェクトを返します。

エラーがどのように返されるかの詳細については、「エラー応答」を参照してください。

例

要求

要求本文で、subscription オブジェクトの JSON 表記を指定します。 clientState と latestSupportedTlsVersion フィールドは省略可能です。

この要求は、現在サインインしているユーザーが受信した新しいメールに関する変更通知のサブスクリプションを作成します。

POST https://graph.microsoft.com/beta/subscriptions
Content-type: application/json

{
   "changeType": "created",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "me/mailFolders('Inbox')/messages",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue",
   "latestSupportedTlsVersion": "v1_2"
}

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

// Dependencies
using Microsoft.Graph.Beta.Models;

var requestBody = new Subscription
{
	ChangeType = "created",
	NotificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient",
	Resource = "me/mailFolders('Inbox')/messages",
	ExpirationDateTime = DateTimeOffset.Parse("2016-11-20T18:23:45.9356913Z"),
	ClientState = "secretClientValue",
	LatestSupportedTlsVersion = "v1_2",
};

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

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

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

requestBody := graphmodels.NewSubscription()
changeType := "created"
requestBody.SetChangeType(&changeType) 
notificationUrl := "https://webhook.azurewebsites.net/api/send/myNotifyClient"
requestBody.SetNotificationUrl(&notificationUrl) 
resource := "me/mailFolders('Inbox')/messages"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2016-11-20T18:23:45.9356913Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "secretClientValue"
requestBody.SetClientState(&clientState) 
latestSupportedTlsVersion := "v1_2"
requestBody.SetLatestSupportedTlsVersion(&latestSupportedTlsVersion) 

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

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

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

Subscription subscription = new Subscription();
subscription.setChangeType("created");
subscription.setNotificationUrl("https://webhook.azurewebsites.net/api/send/myNotifyClient");
subscription.setResource("me/mailFolders('Inbox')/messages");
OffsetDateTime expirationDateTime = OffsetDateTime.parse("2016-11-20T18:23:45.9356913Z");
subscription.setExpirationDateTime(expirationDateTime);
subscription.setClientState("secretClientValue");
subscription.setLatestSupportedTlsVersion("v1_2");
Subscription result = graphClient.subscriptions().post(subscription);

const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
   changeType: 'created',
   notificationUrl: 'https://webhook.azurewebsites.net/api/send/myNotifyClient',
   resource: 'me/mailFolders(\'Inbox\')/messages',
   expirationDateTime: '2016-11-20T18:23:45.9356913Z',
   clientState: 'secretClientValue',
   latestSupportedTlsVersion: 'v1_2'
};

await client.api('/subscriptions')
	.version('beta')
	.post(subscription);

<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Models\Subscription;


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

$requestBody = new Subscription();
$requestBody->setChangeType('created');
$requestBody->setNotificationUrl('https://webhook.azurewebsites.net/api/send/myNotifyClient');
$requestBody->setResource('me/mailFolders(\'Inbox\')/messages');
$requestBody->setExpirationDateTime(new \DateTime('2016-11-20T18:23:45.9356913Z'));
$requestBody->setClientState('secretClientValue');
$requestBody->setLatestSupportedTlsVersion('v1_2');

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

Import-Module Microsoft.Graph.Beta.ChangeNotifications

$params = @{
	changeType = "created"
	notificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient"
	resource = "me/mailFolders('Inbox')/messages"
	expirationDateTime = [System.DateTime]::Parse("2016-11-20T18:23:45.9356913Z")
	clientState = "secretClientValue"
	latestSupportedTlsVersion = "v1_2"
}

New-MgBetaSubscription -BodyParameter $params

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.models.subscription import Subscription
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = Subscription(
	change_type = "created",
	notification_url = "https://webhook.azurewebsites.net/api/send/myNotifyClient",
	resource = "me/mailFolders('Inbox')/messages",
	expiration_date_time = "2016-11-20T18:23:45.9356913Z",
	client_state = "secretClientValue",
	latest_supported_tls_version = "v1_2",
)

result = await graph_client.subscriptions.post(request_body)

要求本文で、subscription オブジェクトの JSON 表記を指定します。 clientState と latestSupportedTlsVersion フィールドは省略可能です。

サブスクリプションの重複動作

重複するサブスクリプションは許可されません。 サブスクリプション要求に、既存のサブスクリプションに含まれる同じ changeType および リソース の値が含まれている場合、要求は失敗し、HTTP エラー コードが 409 Conflictされ、エラー メッセージが Subscription Id <> already exists for the requested combinationされます。

リソースの例

リソース プロパティの有効な値を次に示します。

応答

次の例は応答を示しています。

注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/beta/$metadata#subscriptions/$entity",
  "id": "7f105c7d-2dc5-4530-97cd-4e7ae6534c07",
  "resource": "me/mailFolders('Inbox')/messages",
  "applicationId": "24d3b144-21ae-4080-943f-7067b395b913",
  "changeType": "created",
  "clientState": "secretClientValue",
  "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
  "expirationDateTime": "2016-11-20T18:23:45.9356913Z",
  "creatorId": "8ee44408-0679-472c-bc2a-692812af3437",
  "latestSupportedTlsVersion": "v1_2",
  "notificationContentType": "application/json"
}

例 2: Web プッシュ エンドポイントを対象とするサブスクリプションを作成する

次の例では、暗号化された変更通知をブラウザーネイティブの Web プッシュ エンドポイント ( web.push.apple.com、 fcm.googleapis.com、 updates.push.services.mozilla.com など) に配信するサブスクリプションを作成します。

このサブスクリプションを作成する前に、ブラウザー ベースのアプリケーションで次の条件を満たしている必要があります。

1. サブスクリプション コレクションで getVapidPublicKey 関数を呼び出して、Microsoft Graph の VAPID 公開キー (RFC 8292) を取得します。
2. PushManager.subscribe({ applicationServerKey: <vapidPublicKey> }) を呼び出して、ブラウザーのプッシュ サービスに登録します。 ブラウザーは、endpoint、p256dh、auth の値を含むPushSubscriptionを返します。

次に、アプリケーションは、 notificationUrl を最小プッシュ サービス エンドポイント URL に設定し、 vapidPublicKey、 webPushEncryptionP256dhPublicKey、および webPushEncryptionSecret プロパティをブラウザによって返される値に設定してサブスクリプションを作成します。 作成後、Microsoft Graph は、格納されているキーを使用して RFC 8291 に従って各通知を暗号化し、プッシュ サービスに投稿する前に VAPID で要求に署名します。

要求

POST https://graph.microsoft.com/beta/subscriptions
Content-type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://web.push.apple.com/QKmFUwSBFK8g7iY4t1...",
  "resource": "me/mailFolders('Inbox')/messages",
  "expirationDateTime": "2026-12-31T11:00:00.0000000Z",
  "clientState": "secretClientValue",
  "vapidPublicKey": "BNKm...base64url-encoded-server-vapid-public-key...",
  "webPushEncryptionP256dhPublicKey": "BNcR...base64url-encoded-client-public-key...",
  "webPushEncryptionSecret": "tBHI...base64url-encoded-auth-secret..."
}

メモ:webPushEncryptionSecret プロパティは書き込み専用です。 GET応答で返されることはありません (nullとして返されます)。 値はシークレットとして扱います。

通知エンドポイントの検証

( notificationUrl プロパティで指定される) サブスクリプション通知エンドポイントは、「 ユーザー データの変更に関する通知の設定」で説明されているように検証要求に応答できる必要があります。 検証に失敗した場合、サブスクリプションを作成する要求は「400 要求が正しくありません」というエラーを返します。