chatMessages: デルタchatMessages: delta

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

重要

/betaMicrosoft Graph のバージョンの api は変更される可能性があります。APIs under the /beta version in Microsoft Graph are subject to change. 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。Use of these APIs in production applications is not supported. API が v2.0 で利用できるかどうかを確認するには、 バージョン セレクターを使用します。To determine whether an API is available in v1.0, use the Version selector.

チームチャネルメッセージの一覧を取得します (返信は含めず)。Retrieve the list of messages (without the replies) in a channel of a team. デルタ クエリを使用すると、チャネルで新しいメッセージや更新されたメッセージを取得できます。By using delta query, you can get new or updated messages in a channel.

注: デルタでは、過去 8 か月以内のメッセージのみが返されます。Note: Delta will only return messages within the last eight months. 古いメッセージを取得するには、GET /teams/{id}/channels/{id}/messages を使用できます。You can use GET /teams/{id}/channels/{id}/messages to retrieve older messages.

デルタ クエリでは、指定したチャネル内のすべてのメッセージを取得する完全な同期と、最後の同期以降にチャネルで変更されたメッセージを取得する増分同期の両方がサポートされています。Delta query supports both full synchronization that retrieves all the messages in the specified channel, and incremental synchronization that retrieves those messages that have been added or changed in the channel since the last synchronization. 通常は、最初の完全同期を実行して、その後、そのカレンダー ビューへの増分の変更を定期的に取得します。Typically, you would do an initial full synchronization, and then get incremental changes to that calendar view periodically.

メッセージの返信を取得するには、メッセージの返信一覧の操作またはメッセージの返信取得の操作を使用します。To get the replies for a message, use the list message replies or the get message reply operation.

デルタ関数を使用した GET 要求は、次のいずれかを返します。A GET request with the delta function returns either:

  • nextLink (デルタ関数の呼び出しと skipToken を使用した URL を含みます)、またはA nextLink (that contains a URL with a delta function call and a skipToken), or
  • deltaLink (デルタ関数の呼び出しと deltaToken を使用した URL を含みます)。A deltaLink (that contains a URL with a delta function call and deltaToken).

状態トークンは、クライアントに対して完全に不透明です。State tokens are completely opaque to the client. 変更追跡のラウンドを続行する手順は、最後の GET 要求から返された nextLink または deltaLink の URL を、その同じカレンダー ビューの次のデルタ関数呼び出しにコピーして適用するだけです。To proceed with a round of change tracking, simply copy and apply the nextLink or deltaLink URL returned from the last GET request to the next delta function call for that same calendar view. 応答で返される deltaLink は、変更追跡の現在のラウンドが完了したことを示します。A deltaLink returned in a response signifies that the current round of change tracking is complete. deltaLink URL を保存して、次のラウンドを開始する際に使用することができます。You can save and use the deltaLink URL when you begin the next round.

詳細については、デルタ クエリに関するドキュメントを参照してください。For more information, see the delta query documentation.

アクセス許可Permissions

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

アクセス許可の種類Permission Type アクセス許可 (特権の小さいものから大きいものへ)Permissions (from least to most privileged)
委任 (職場または学校のアカウント)Delegated (work or school account) ChannelMessage.Read.All、Group.Read.All、Group.ReadWrite.AllChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All
委任 (個人用 Microsoft アカウント)Delegated (personal Microsoft account) サポート対象外Not Supported
アプリケーションApplication ChannelMessage.Read.Group*、ChannelMessage.Read.All、Group.Read.All、Group.ReadWrite.AllChannelMessage.Read.Group*, ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All

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

注意

この API をアプリケーションのアクセス許可で呼び出す前に、アクセスを要求する必要があります。Before calling this API with application permissions, you must request access. 詳細については、「Microsoft Teams の保護された API」を参照してください。For details, see Protected APIs in Microsoft Teams.

HTTP 要求HTTP request

GET /teams/{id}/channels/{id}/messages/delta

クエリ パラメーターQuery parameters

チャネル メッセージの変更を追跡すると、1 つ以上のデルタ関数呼び出しのラウンドが発生します。Tracking changes in channel messages incurs a round of one or more delta function calls. 任意のクエリ パラメーター ($deltatoken$skiptoken以外) を使用する場合は、最初のデルタ要求でこれを指定する必要があります。If you use any query parameter (other than $deltatoken and $skiptoken), you must specify it in the initial delta request. Microsoft Graph は、応答で提供される nextLink または deltaLink の URL のトークン部分に指定したパラメーターを自動的にエンコードします。Microsoft Graph automatically encodes any specified parameters into the token portion of the nextLink or deltaLink URL provided in the response.

すべてのクエリ パラメーターを最初に 1 回指定しておくだけで済みます。You only need to specify any query parameters once upfront.

その後の要求では、以前の応答で得られた nextLinkdeltaLink の URL をコピーして適用します。エンコード済みのパラメーターがこの URL に既に含まれているためです。In subsequent requests, copy and apply the nextLink or deltaLink URL from the previous response, as that URL already includes the encoded parameters.

クエリ パラメーターQuery parameter 種類Type 説明Description
$deltatoken stringstring 前回のデルタ関数呼び出しの deltaLink URL で返された状態トークンで、そのラウンドの変更追跡が完了したことを示します。A state token returned in the deltaLink URL of the previous delta function call, indicating the completion of that round of change tracking. このコレクションについて、このトークンを含む、deltaLink URL 全体を次の変更追跡のラウンドの最初の要求に保存し、適用します。Save and apply the entire deltaLink URL including this token in the first request of the next round of change tracking for that collection.
$skiptoken stringstring 以前のデルタ関数呼び出しの nextLink URL 内で返された状態トークンで、同じカレンダー ビュー内に追跡する必要がある変更が他にもあることを示しています。A state token returned in the nextLink URL of the previous delta function call, indicating that there are further changes to be tracked.

オプションの OData クエリ パラメーターOptional OData query parameters

次の OData クエリ パラメーターはこの API でサポートされています。The following OData query parameters are supported by this API:

  • $topは、1 回の呼び出しで取得するメッセージの最大数を表します。$top, represents maximum number of messages to fetch in a call. 上限は 50 です。The upper limit is 50.
  • $skipは、一覧の先頭でスキップするメッセージの数を表します。$skip, represents how many messages to skip at the beginning of the list.
  • $filter により、特定の条件を満たすメッセージを返すことが可能になります。$filter allows returning messages that meet a certain criteria. フィルター処理がサポートされているプロパティは lastModifiedDateTime のみで、サポートされている演算子は gt のみです。The only property that supports filtering is lastModifiedDateTime, and only the gt operator is supported. たとえば、../messages/delta?$filter=lastModifiedDateTime gt 2019-02-27T07:13:28.000z は、指定した日時以降に作成または変更されたすべてのメッセージを取得します。For example, ../messages/delta?$filter=lastModifiedDateTime gt 2019-02-27T07:13:28.000z will fetch any messages created or changed after the specified date time.

要求ヘッダーRequest headers

ヘッダーHeader Value
AuthorizationAuthorization ベアラー {トークン}。必須。Bearer {token}. Required.
Content-TypeContent-Type application/jsonapplication/json

要求本文Request Body

このメソッドには、要求本文を指定しません。Do not supply a request body for this method.

応答Response

このメソッドは、成功すると 200 OK 応答コードと chatMessage オブジェクトのコレクションを応答本文で返します。If successful, this method returns a 200 OK response code and a collection of chatMessage objects in the response body. 応答には nextLink URL または deltaLink URLも含まれます。The response also includes a nextLink URL or a deltaLink URL.

Examples

例 1: 初期同期Example 1: Initial synchronization

次の例では、特定のチャネル内のメッセージを同期するための、3 つの一連の要求を示しています。The following example shows a series of three requests to synchronize the messages in the given channel. チャネルにはメッセージが 5 つあります。There are five messages in the channel.

簡潔にするため、サンプルの応答にはイベントのプロパティのサブセットのみを表示します。実際の呼び出しでは、ほとんどのイベント プロパティが返されます。For brevity, the sample responses show only a subset of the properties for an event. In an actual call, most event properties are returned.

次のラウンドで行う操作も参照してください。See also what you'll do in the next round.

最初の要求Initial request

この例では、チャネルのメッセージは初めて同期されるため、最初の同期要求には状態トークンは含まれません。In this example, the channel messages are being synchronized for the first time, so the initial sync request does not include any state token. このラウンドは、そのカレンダー ビュー内のすべてのイベントを返します。This round will return all the events in that calendar view.

要求では、オプションの要求ヘッダーである odata.top が指定され、一度に 2 つのイベントが返されます。The request specifies the optional request header, odata.top, returning 2 events at a time.

GET /teams/{id}/channels/{id}/messages/delta?$top=2

最初の要求の応答Initial request response

応答には、2 つのメッセージと skipToken が含まれた @odata.nextLink 応答ヘッダーが含まれています。The response includes two messages and a @odata.nextLink response header with a skipToken. nextLink URL は、取得するべきメッセージが他にもチャネルにあることを示します。The nextLink URL indicates there are more messages in the channel to get.

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

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "/$metadata#Collection(Microsoft.Teams.GraphSvc.chatMessage)",
    "@odata.nextLink": "/teams('id')/channels('id')/messages/delta?$skiptoken=c3RhcnRUaW1lPTE1NTEyMTUzMjU0NTkmcGFnZVNpemU9MjA%3d",
    "value": [
        {
            "id": "id-value",
            "replyToId": "id-value",
            "from" : {
                "user": { 
                    "id": "id-value",
                    "displayName": "John Doe"
                }  
            },
            "etag": "id-value",
            "messageType": "message",
            "createdDateTime": "2019-03-06T07:40:20.152Z",
            "lastModifiedDateTime": "2019-03-06T07:40:20.152Z",
            "body": {
                "content": "Hello World",
                "contentType": "Text"
            },
            "attachments": [],
            "mentions": [],
            "importance": "normal",
            "reactions": [],
            "locale": "en-us"
        },
        {
            "id": "id-value",
            "replyToId": "id-value",
            "from" : {
                "user": { 
                    "id": "id-value",
                    "displayName": "John Doe"
                }  
            },
            "etag": "id-value",
            "messageType": "message",
            "createdDateTime": "2019-03-06T08:40:20.152Z",
            "lastModifiedDateTime": "2019-03-06T08:40:20.152Z",
            "body": {
                "content": "Hello World",
                "contentType": "Text"
            },
            "attachments": [],
            "mentions": [],
            "importance": "normal",
            "reactions": [],
            "locale": "en-us"
        }
    ]
}

2 番目の要求Second request

2 番目の要求では、前の応答で返された nextLink URL が指定されます。The second request specifies the nextLink URL returned from the previous response. 最初の要求と同じ top パラメーターを指定する必要がない点に注意してください。これは、nextLink URL の skipToken によってエンコードされて含まれるためです。Notice that it no longer has to specify the same top parameters as in the initial request, as the skipToken in the nextLink URL encodes and includes them.

GET /teams/{id}/channels/{id}/messages/delta?$skiptoken=c3RhcnRUaW1lPTE1NTEyMTUzMjU0NTkmcGFnZVNpemU9MjA%3d

2 番目の要求の応答Second request response

2 番目の応答には、次の 2 つのメッセージと @odata.nextLink を含む skipToken 応答ヘッダーが返されます。これは、取得するべきメッセージが他にもチャネルにあることを示します。The second response returns the next 2 messages and a @odata.nextLink response header with a skipToken, indicates there are more messages in the channel to get.

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

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "/$metadata#Collection(Microsoft.Teams.GraphSvc.chatMessage)",
    "@odata.nextLink": "/teams('id')/channels('id')/messages/delta?$skiptoken=c3RhcnRUaW1lPTE1NTEyODcyMzY2NzgmcGFnZVNpemU9MjA%3d",
    "value": [
        {
            "id": "id-value",
            "replyToId": "id-value",
            "from" : {
                "user": { 
                    "id": "id-value",
                    "displayName": "John Doe"
                }  
            },
            "etag": "id-value",
            "messageType": "message",
            "createdDateTime": "2019-03-06T09:40:20.152Z",
            "lastModifiedDateTime": "2019-03-06T09:40:20.152Z",
            "body": {
                "content": "Hello World",
                "contentType": "Text"
            },
            "attachments": [],
            "mentions": [],
            "importance": "normal",
            "reactions": [],
            "locale": "en-us"
        },
        {
            "id": "id-value",
            "replyToId": "id-value",
            "from" : {
                "user": { 
                    "id": "id-value",
                    "displayName": "John Doe"
                }  
            },
            "etag": "id-value",
            "messageType": "message",
            "createdDateTime": "2019-03-06T09:50:20.152Z",
            "lastModifiedDateTime": "2019-03-06T09:50:20.152Z",
            "body": {
                "content": "Hello World",
                "contentType": "Text"
            },
            "attachments": [],
            "mentions": [],
            "importance": "normal",
            "reactions": [],
            "locale": "en-us"
        }
    ]
}

3 番目の要求Third request

3 番目の要求では、最後の同期要求から返された最新の nextLink を引き続き使用します。The third request continues to use the latest nextLink returned from the last sync request.

GET /teams/{id}/channels/{id}/messages/delta?$skiptoken=c3RhcnRUaW1lPTE1NTEyODcyMzY2NzgmcGFnZVNpemU9MjA%3d

3 番目の要求の応答Third request response

3 番目の応答には、チャネルの残りのメッセージと deltaToken を含む @odata.deltaLink 応答ヘッダーが返されます。これは、チャネルのすべてのメッセージが読まれたことを示します。The third response returns the only remaining messages in the channel and a @odata.deltaLink response header with a deltaToken which indicates that all messages in the channel have been read. このdeltaLink URL を保存し、次のラウンドでこの時点以降のすべての新しいメッセージのクエリを行うために使用します。Save and use the deltaLink URL to query for any new messages starting from this point in the next round.

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

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "/$metadata#Collection(Microsoft.Teams.GraphSvc.chatMessage)",
    "@odata.deltaLink": "/teams('id')/channels('id')/messages/delta?$deltatoken=c3RhcnRUaW1lPTE1NTEyODc1ODA0OTAmcGFnZVNpemU9MjA%3d",
    "value": [
        {
            "id": "id-value",
            "replyToId": "id-value",
            "from" : {
                "user": { 
                    "id": "id-value",
                    "displayName": "John Doe"
                }  
            },
            "etag": "id-value",
            "messageType": "message",
            "createdDateTime": "2019-03-06T10:40:20.152Z",
            "lastModifiedDateTime": "2019-03-06T10:40:20.152Z",
            "body": {
                "content": "Hello World",
                "contentType": "Text"
            },
            "attachments": [],
            "mentions": [],
            "importance": "normal",
            "reactions": [],
            "locale": "en-us"
        }
    ]
}

例 2: 追加の変更を取得するExample 2: Retrieving additional changes

前回のラウンドの最後の応答からの deltaLink を使用すると、それ以降にそのチャネルで (追加または更新によって) 変更されたこれらのメッセージのみを取得できます。Using the deltaLink from the last request in the last round, you will be able to get only those messages that have changed (by being added, or updated) in that channel since then. 応答で同じ最大ページ サイズを維持することを前提とすると、要求は次のようになります。Your request will look like the following, assuming you prefer to keep the same maximum page size in the response:

要求Request

GET /teams/{id}/channels/{id}/messages/delta?$deltatoken=c3RhcnRUaW1lPTE1NTEyODc1ODA0OTAmcGFnZVNpemU9MjA%3d

応答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 200 OK
Content-type: application/json

{
    "@odata.context": "/$metadata#Collection(Microsoft.Teams.GraphSvc.chatMessage)",
    "@odata.deltaLink": "/teams('id')/channels('id')/messages/delta?$deltatoken=c3RhcnRUaW1l5Ti1NTEyODc1ODB0OTAyXGFdZVNpemU9MjA%3d",
    "value": [
        {
            "id": "id-value",
            "replyToId": "id-value",
            "from" : {
                "user": { 
                    "id": "id-value",
                    "displayName": "John Doe"
                }  
            },
            "etag": "id-value",
            "messageType": "message",
            "createdDateTime": "2019-03-06T10:40:20.152Z",
            "lastModifiedDateTime": "2019-03-06T10:40:20.152Z",
            "body": {
                "content": "Hello World",
                "contentType": "Text"
            },
            "attachments": [],
            "mentions": [],
            "importance": "normal",
            "reactions": [],
            "locale": "en-us"
        }
    ]
}