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

名前空間: microsoft.graph

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

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

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

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

アクセス許可

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

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

chatMessage

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

Prefer: include-unknown-enum-members要求ヘッダーを使用して、chatMessagemessageTypeの進化可能な列挙型で次の値を取得します。/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 を使用してチャットの変更通知を取得する」を参照してください。

要求の例

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

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

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 インスタンスをサブスクライブすることはできません。

職場または学校および SharePoint 用の OneDrive では、 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"
}

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

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