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

• 2020/12/08
• • d
  • o

名前空間: microsoft.graphNamespace: microsoft.graph

変更の要求された種類が Microsoft Graph の指定されたリソースに発生したときに変更通知を受信するため、リスナー アプリケーションに登録します。Subscribes a listener application to receive change notifications when the requested type of changes occur to the specified resource in Microsoft Graph.

アクセス許可Permissions

サブスクリプションを作成するには、リソースに対する読み取りアクセス許可が必要です。Creating a subscription requires read permission to the resource. たとえば、メッセージの変更通知を取得するには、アプリにはメールの読み取りアクセス許可が必要です。For example, to get change notifications on messages, your app needs the Mail.Read permission.

要求されたリソースとアクセス許可の種類 (委任およびアプリケーション) によっては、以下の表で指定されているアクセス許可がこの API を呼び出すために最小限必要な特権となります。Depending on the resource and the permission type (delegated or application) requested, the permission specified in the following table is the least privileged required to call this API. アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。To learn more, including how to choose permissions, see Permissions.

注: * でマークされた権限は、リソース固有の同意を使用します。Note: Permissions marked with * use resource-specific consent.

chatMessagechatMessage

[委任されたアクセス許可を持つ メッセージ サブスクリプションは、リソースデータをサポートしていません (この データ は必須である必要があり false ます)。また、暗号化は必要ありません。chatMessage subscriptions with delegated permissions do not support resource data (includeResourceData must be false), and do not require encryption.

アプリケーションへのアクセス許可を持つ chatMessage サブスクリプションにはリソース データが含まれており、暗号化が必要です。chatMessage subscriptions with application permissions include resource data, and require encryption. encryptionCertificate が指定されていない場合、サブスクリプションの作成は失敗します。Subscription creation will fail if encryptionCertificate is not specified. chatMessage サブスクリプションを作成する前に、アクセスを要求する必要があります。Before creating a chatMessage subscription, you must request access. 詳細については、「Microsoft Teams の保護された API」を参照してください。For details, see Protected APIs in Microsoft Teams.

注: /teams/getAllMessages および /chats/getAllMessages は、必要なライセンスを持つユーザーが利用できます。Note: /teams/getAllMessages and /chats/getAllMessages are available to users that have the required licenses.

注: /chats/getAllMessages テナントが所有するチャットからのメッセージのみを返します。Note: /chats/getAllMessages only returns messages from chats owned by the tenant. チャットスレッドがテナント外部のユーザーによって開始された場合、そのチャットスレッドはテナントによって所有されず、変更通知は作成されません。If a chat thread is initiated by a user outside the tenant, that chat thread is not owned by the tenant, and does not create change notifications.

driveItemdriveItem

OneDrive アイテムのサブスクリプションには追加の制限が適用されます。Additional limitations apply for subscriptions on OneDrive items. この制限は、サブスクリプションの作成および管理 (取得、更新、削除) に適用されます。The limitations apply to creating as well as managing (getting, updating, and deleting) subscriptions.

個人用 OneDrive では、そのドライブのルート フォルダーまたは任意のサブフォルダーにサブスクライブできます。On a personal OneDrive, you can subscribe to the root folder or any subfolder in that drive. OneDrive for Business の場合、サブスクライブできるのはルート フォルダーのみです。On OneDrive for Business, you can subscribe to only the root folder. サブスクライブしたフォルダー、または階層内の任意のファイル、フォルダー、あるいは他の driveItem インスタンスに関する変更の要求された種類についての変更通知が送信されます。Change notifications are sent for the requested types of changes on the subscribed folder, or any file, folder, or other driveItem instances in its hierarchy. 個別のファイルなどのフォルダーではない、ドライブ インスタンスまたは driveItem インスタンスをサブスクライブすることはできません。You cannot subscribe to drive or driveItem instances that are not folders, such as individual files.

連絡先、イベント、メッセージcontact, event, and message

Outlook アイテムのサブスクリプションには追加の制限が適用されます。Additional limitations apply for subscriptions on Outlook items. この制限は、サブスクリプションの作成および管理 (取得、更新、削除) に適用されます。The limitations apply to creating as well as managing (getting, updating, and deleting) subscriptions.

• 委任されたアクセス許可では、サインインしているユーザーのメールボックス内のフォルダーにあるアイテムのみをサブスクライブできます。Delegated permission supports subscribing to items in folders in only the signed-in user's mailbox. 委任されたアクセス許可 Calendars.Read を使用して、別のユーザーのメールボックス内のイベントをサブスクライブすることなどはできません。For example, you cannot use the delegated permission Calendars.Read to subscribe to events in another user’s mailbox.

• 共有または委任 フォルダーの Outlook 連絡先、イベント、メッセージの変更通知をサブスクライブするには、次のようにします。To subscribe to change notifications of Outlook contacts, events, or messages in shared or delegated folders:

  • 対応するアプリケーション アクセス許可を使用して、テナントの 任意 のユーザーのフォルダーまたはメールボックス内にあるアイテムの変更をサブスクライブします。Use the corresponding application permission to subscribe to changes of items in a folder or mailbox of any user in the tenant.
  • Outlook 共有アクセス許可 (Contacts.Read.Shared、Calendars.Read.Shared、Mail.Read.Shared、および対応する読み取り/書き込み) は使用しないでください。それらは、共有フォルダーまたは委任フォルダーにあるアイテムの変更通知のサブスクライブをサポート していない からです。Do not use the Outlook sharing permissions (Contacts.Read.Shared, Calendars.Read.Shared, Mail.Read.Shared, and their read/write counterparts), as they do not support subscribing to change notifications on items in shared or delegated folders.

プレゼンスpresence

プレゼンス サブスクリプションは 暗号化を必要とします。presence subscriptions require encryption. encryptionCertificate が指定されていない場合、サブスクリプションの作成は失敗します。Subscription creation will fail if encryptionCertificate is not specified.

HTTP 要求HTTP request

POST /subscriptions

要求ヘッダーRequest headers

応答Response

成功した場合、このメソッドは応答 201 Created コードと、応答本文で subscription オブジェクトを返します。If successful, this method returns a 201 Created response code and a subscription object in the response body.

エラーがどのように返されるかの詳細については、「エラー応答」を参照してください。For details about how errors are returned, see Error responses.

例Example

要求Request

要求本文で、subscription オブジェクトの JSON 表記を指定します。In the request body, supply a JSON representation of the subscription object. clientState と latestSupportedTlsVersion フィールドは省略可能です。The clientState and latestSupportedTlsVersion fields are optional.

この要求は、現在サインインしているユーザーが受信した新しいメールに関する変更通知のサブスクリプションを作成します。This request creates a subscription for change notifications about new mail received by the currently signed in user.

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"
}

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

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"
};

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

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/beta/";
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];

IGraphServiceClient 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 = CalendarSerializer.deserialize("2016-11-20T18:23:45.9356913Z");
subscription.clientState = "secretClientValue";
subscription.latestSupportedTlsVersion = "v1_2";

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

要求本文で、subscription オブジェクトの JSON 表記を指定します。In the request body, supply a JSON representation of the subscription object. clientState と latestSupportedTlsVersion フィールドは省略可能です。The clientState and latestSupportedTlsVersion fields are optional.

リソースの例Resources examples

Resource プロパティの有効な値は次のとおりです。The following are valid values for the resource property.

注: me で始まるパスは、me ではなく users/{id} でも使用して、現在のユーザーではなく特定のユーザーをターゲットにすることができます。Note: Any path starting with me can also be used with users/{id} instead of me to target a specific user instead of the current user.

応答Response

次の例は応答を示しています。The following example shows the response.

注: 読みやすくするために、ここに示す応答オブジェクトは短くされている場合があります。実際の呼び出しからは、すべてのプロパティが返されます。Note: The response object shown here might be shortened for readability. All the properties will be returned from an actual call.

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

{
  "@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"
}

通知エンドポイントの検証Notification endpoint validation

「ユーザーデータの変更の通知を設定する」の説明に従って、 notificationurl プロパティで指定されたサブスクリプション通知エンドポイントは、検証要求に応答できる必要があります。The subscription notification endpoint (specified in the notificationUrl property) must be capable of responding to a validation request as described in Set up notifications for changes in user data. 検証に失敗した場合、サブスクリプションを作成する要求は「400 要求が正しくありません」というエラーを返します。If validation fails, the request to create the subscription returns a 400 Bad Request error.