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

[アーティクル]
06/30/2022

名前空間: microsoft.graph

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

変更通知のサブスクライブをサポートするリソースのリストについては、[アクセス許可] セクションの表を参照してください。

一部のリソースは、変更通知に暗号化されたリソースデータを含めるオプションをサポートしています。これらのリソースには、chatMessage、連絡先、イベント、メッセージ、およびプレゼンスが含まれます。詳細については、「Microsoft Graph でのリソースデータを含む変更通知の設定」および「Outlook リソースの変更通知」を参照してください。

アクセス許可

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

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

サポートされているリソース	委任 (職場または学校のアカウント)	委任 (個人用 Microsoft アカウント)	アプリケーション
callRecord (/communications/callRecords)	非サポート	非サポート	CallRecords.Read.All
チャネル (/teams/getAllChannels – 組織内のすべてのチャネル)	非サポート	非サポート	Channel.ReadBasic.All、ChannelSettings.Read.All
チャネル (/teams/{id}/channels)	Channel.ReadBasic.All、ChannelSettings.Read.All	非サポート	Channel.ReadBasic.All、ChannelSettings.Read.All
チャット (/chats – 組織内のすべてのチャット)	サポート対象外	非サポート	Chat.ReadBasic.All、 Chat.Read.All、 Chat.ReadWrite.All
チャット (/chats/{id})	Chat.ReadBasic、 Chat.Read、 Chat.ReadWrite	非サポート	ChatSettings.Read.Chat , ChatSettings.ReadWrite.Chat, Chat.Manage.Chat*, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
chatMessage (/teams/{id}/channels/{id}/messages)	ChannelMessage.Read.All	非サポート	ChannelMessage.Read.Group*、ChannelMessage.Read.All
chatMessage (/teams/getAllMessages -- all channel messages in organization)	非サポート	非サポート	ChannelMessage.Read.All
chatMessage (/chats/{id}/messages)	非サポート	非サポート	Chat.Read.All
chatMessage (/chats/getAllMessages -- all chat messages in organization)	非サポート	非サポート	Chat.Read.All
チャットメッセージ (/users/{id}/chats/getAllMessages -- 特定のユーザーが参加しているすべてのチャットのチャットメッセージ)	Chat.Read、Chat.ReadWrite	非サポート	Chat.Read.All、Chat.ReadWrite.All
contact	Contacts.Read	Contacts.Read	Contacts.Read
conversationMember (/chats/getAllMembers)	サポート対象外	非サポート	ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
conversationMember (/chats/{id}/members)	ChatMember.Read, ChatMember.ReadWrite, Chat.ReadBasic, Chat.Read, Chat.ReadWrite	サポート対象外	ChatMember.Read.Chat , Chat.Manage.Chat, ChatMember.Read.All, ChatMember.ReadWrite.All, Chat.ReadBasic.All, Chat.Read.All, Chat.ReadWrite.All
conversationMember (/teams/{id}/members)	TeamMember.Read.All	非サポート	TeamMember.Read.All
conversationMember (/teams/{id}/channels/getAllMembers)	サポート対象外	非サポート	ChannelMember.Read.All
driveItem (ユーザーの個人用 OneDrive)	サポート対象外	Files.ReadWrite	サポート対象外
driveItem (OneDrive for Business)	Files.ReadWrite.All	サポート対象外	Files.ReadWrite.All
イベント	Calendars.Read	Calendars.Read	Calendars.Read
グループ	Group.Read.All	サポート対象外	Group.Read.All
グループ会話	Group.Read.All	非サポート	非サポート
リスト	Sites.ReadWrite.All	サポート対象外	Sites.ReadWrite.All
メッセージ	Mail.ReadBasic, Mail.Read	Mail.ReadBasic, Mail.Read	Mail.Read
プレゼンス	Presence.Read.All	非サポート	サポート対象外
プリンター	非サポート	非サポート	Printer.Read.All, Printer.ReadWrite.All
printTaskDefinition	非サポート	非サポート	PrintTaskDefinition.ReadWrite.All
セキュリティの警告	SecurityEvents.ReadWrite.All	サポート対象外	SecurityEvents.ReadWrite.All
team (/teams – 組織内のすべてのチーム)	非サポート	非サポート	Team.ReadBasic.All、TeamSettings.Read.All
team (/teams/{id})	Team.ReadBasic.All、TeamSettings.Read.All	非サポート	Team.ReadBasic.All、TeamSettings.Read.All
todoTask	Tasks.ReadWrite	Tasks.ReadWrite	非サポート
user	User.Read.All	User.Read.All	User.Read.All

前の表に記載されているように、アクセス許可を使用することをお勧めします。セキュリティ上の制限により、読み取りアクセス許可のみが必要な場合、Microsoft Graph サブスクリプションは書き込みアクセス許可をサポートしません。

注: * でマークされた権限は、リソース固有の同意を使用します。

chatMessage

chatMessage サブスクリプションは、リソースデータを含めるように指定できます。リソースデータを含めるように指定した場合 (includeResourceData を true に設定)、暗号化が必要です。そのようなサブスクリプションに encryptionCertificate が指定されていない場合、サブスクリプションの作成は失敗します。アプリケーションのアクセス許可を使用して chatMessage サブスクリプションを作成する前に、アクセスを要求する必要がある場合があります。詳細については、「Microsoft Teams の保護された API」を参照してください。

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

注意

/teams/getAllMessages、/chats/getAllMessages、/me/chats/getAllMessages、および /users/{id}/chats/getAllMessages には、ライセンスと支払いの要件があります。 /teams/getAllMessages と /chats/getAllMessages では、model=A と model=B の両方のクエリパラメーターがサポートされ、/me/chats/getAllMessages と /users/{id}/chats/getAllMessages は、 model=B のみがサポートされています。モデルが指定されていない場合は、評価モードが使用されます。

conversationMember

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

注意

/teams/getAllMembers と /chats/getAllMembers にはライセンス要件と支払い要件があります。 /teams/getAllMembers と /chats/getAllMembers では model=A と model=B の両方がサポートされています。モデルが指定されていない場合は、評価モードが使用されます。

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

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

要求の例

要求本文の リソース プロパティで、model クエリパラメーターを指定します。

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

{
   "changeType": "created",
   "notificationUrl": "https://webhook.azurewebsites.net/api/send/myNotifyClient",
   "resource": "chats/getAllMessages?model=A",
   "expirationDateTime":"2016-11-20T18:23:45.9356913Z",
   "clientState": "secretClientValue",
   "latestSupportedTlsVersion": "v1_2"
}

driveItem

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

個人用 OneDrive では、そのドライブのルートフォルダーまたは任意のサブフォルダーにサブスクライブできます。 OneDrive for Business の場合、サブスクライブできるのはルートフォルダーのみです。サブスクライブしたフォルダー、または階層内の任意のファイル、フォルダー、あるいは他の driveItem インスタンスに関する変更の要求された種類についての変更通知が送信されます。個別のファイルなどのフォルダーではない、ドライブ インスタンスまたは driveItem インスタンスをサブスクライブすることはできません。

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

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

Outlook の 連絡先、イベント、または メッセージ リソースの変更にサブスクライブできます。

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

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

プレゼンス

プレゼンス でのサブスクリプションには、変更通知に含まれるリソースデータが暗号化されている必要があります。サブスクリプションを作成する場合は、常に encryptionCertificate パラメーターを指定してエラーを回避します。リソースデータが含まれる変更通知を設定するを参照してください。

HTTP 要求

POST /subscriptions

要求ヘッダー

名前	型	説明
Authorization	string	ベアラー {token}。必須。

要求本文

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

応答

成功した場合、このメソッドは 201 Created 応答コードと、応答本文に入った subscription オブジェクトを返します。エラーがどのように返されるかの詳細については、「エラー応答」を参照してください。

例

要求

ユーザーが新しいメールを受信したときに変更通知を送信する要求の例を次に示します。

POST https://graph.microsoft.com/v1.0/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"
}


GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var subscription = 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"
};

await graphClient.Subscriptions
    .Request()
    .AddAsync(subscription);

SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。


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')
    .post(subscription);

SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。


MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/subscriptions"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

MSGraphSubscription *subscription = [[MSGraphSubscription alloc] init];
[subscription setChangeType:@"created"];
[subscription setNotificationUrl:@"https://webhook.azurewebsites.net/api/send/myNotifyClient"];
[subscription setResource:@"me/mailFolders('Inbox')/messages"];
[subscription setExpirationDateTime: "2016-11-20T18:23:45.9356913Z"];
[subscription setClientState:@"secretClientValue"];
[subscription setLatestSupportedTlsVersion:@"v1_2"];

NSError *error;
NSData *subscriptionData = [subscription getSerializedDataWithError:&error];
[urlRequest setHTTPBody:subscriptionData];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];

SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。


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

Subscription subscription = new Subscription();
subscription.changeType = "created";
subscription.notificationUrl = "https://webhook.azurewebsites.net/api/send/myNotifyClient";
subscription.resource = "me/mailFolders('Inbox')/messages";
subscription.expirationDateTime = OffsetDateTimeSerializer.deserialize("2016-11-20T18:23:45.9356913Z");
subscription.clientState = "secretClientValue";
subscription.latestSupportedTlsVersion = "v1_2";

graphClient.subscriptions()
    .buildRequest()
    .post(subscription);

SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestBody := msgraphsdk.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)
result, err := graphClient.Subscriptions().Post(requestBody)

SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。


Import-Module Microsoft.Graph.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-MgSubscription -BodyParameter $params

SDK をプロジェクトに追加し、authProvider インスタンスを作成する方法の詳細については、SDK のドキュメントを参照してください。

要求本文で、subscription オブジェクトの JSON 表記を指定します。clientState および latestSupportedTlsVersion フィールドはオプションです。

リソースの例

以下は、サブスクリプションのリソースプロパティの有効な値です。

リソースの種類	例
通話レコード	`communications/callRecords`
チャットメッセージ	`chats/{id}/messages`, `chats/getAllMessages`, `teams/{id}/channels/{id}/messages`, `teams/getAllMessages`
連絡先	`me/contacts`
会話	`groups('{id}')/conversations`
ドライブ	`me/drive/root`
イベント	`me/events`
グループ	`groups`
リスト	`sites/{site-id}/lists/{list-id}`
メール	`me/mailfolders('inbox')/messages`, `me/messages`
プレゼンス	`/communications/presences/{id}` (単一ユーザー)、`/communications/presences?$filter=id in ('{id}','{id}',…)` (複数のユーザー)
プリンター	`print/printers/{id}/jobs`
printTaskDefinition	`print/taskDefinitions/{id}/tasks`
セキュリティの警告	`security/alerts?$filter=status eq 'New'`
todoTask	`/me/todo/lists/{todoTaskListId}/tasks`
ユーザー	`users`

注: me で始まるパスは、me ではなく users/{id} でも使用して、現在のユーザーではなく特定のユーザーをターゲットにすることができます。

応答

応答の例を次に示します。

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

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

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$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"
}

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

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

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

アクセス許可

chatMessage

conversationMember

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

要求の例

driveItem

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

プレゼンス

HTTP 要求

要求ヘッダー

要求本文

応答

例

要求

リソースの例

応答

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

フィードバック