chatMessages: deltachatMessages: delta

Namespace: microsoft.graphNamespace: microsoft.graph

Importante

As APIs na /beta versão do Microsoft Graph estão sujeitas a alterações.APIs under the /beta version in Microsoft Graph are subject to change. Não há suporte para o uso dessas APIs em aplicativos de produção.Use of these APIs in production applications is not supported. Para determinar se uma API está disponível no v 1.0, use o seletor de versão .To determine whether an API is available in v1.0, use the Version selector.

Recupere a lista de mensagens (sem as respostas) em um canal de uma equipe.Retrieve the list of messages (without the replies) in a channel of a team. Usando a consulta Delta, você pode obter mensagens novas ou atualizadas em um canal.By using delta query, you can get new or updated messages in a channel.

Observação: Delta retornará apenas as mensagens dos últimos oito meses.Note: Delta will only return messages within the last eight months. Você pode usar GET /teams/{id}/channels/{id}/messages para recuperar mensagens mais antigas.You can use GET /teams/{id}/channels/{id}/messages to retrieve older messages.

A consulta Delta é compatível tanto com sincronização completa que recupera todos as mensagens num canal especificado quanto com a sincronização incremental que recupera as mensagens que foram adicionadas ou alteradas no canal desde a última sincronização.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. Normalmente, você faria uma sincronização total inicial e, logo depois, obteria periodicamente alterações incrementais para esse modo de exibição de calendário.Typically, you would do an initial full synchronization, and then get incremental changes to that calendar view periodically.

Para obter as respostas de uma mensagem, utilize use a operação listar respostas da mensagem ou a operação obter resposta da mensagem.To get the replies for a message, use the list message replies or the get message reply operation.

Uma solicitação GET com a função delta traz como resultado uma destas opções:A GET request with the delta function returns either:

  • Uma nextLink (que contém uma URL com uma chamada de função delta e uma skipToken) ouA nextLink (that contains a URL with a delta function call and a skipToken), or
  • Uma deltaLink (que contém uma URL com uma chamada de função delta e deltaToken).A deltaLink (that contains a URL with a delta function call and deltaToken).

Os tokens de estado são completamente opacos para o cliente.State tokens are completely opaque to the client. Para prosseguir com uma fase de controle de alterações, basta copiar e aplicar a URL nextLink ou deltaLink retornada da última solicitação GET para a próxima chamada de função delta do mesmo modo de exibição de calendário.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. Um deltaLink retornado em uma resposta significa que a fase atual do rastreamento de alterações está concluída.A deltaLink returned in a response signifies that the current round of change tracking is complete. Você pode salvar e usar a URL deltaLink quando começar a próxima fase.You can save and use the deltaLink URL when you begin the next round.

Para obter mais informações, consulte a documentação da consulta Delta.For more information, see the delta query documentation.

PermissõesPermissions

Uma das seguintes permissões é obrigatória para chamar esta API. Para saber mais, incluindo como escolher permissões, confira Permissões.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Tipo de permissãoPermission Type Permissões (da com menos para a com mais privilégios)Permissions (from least to most privileged)
Delegado (conta corporativa ou de estudante)Delegated (work or school account) ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.AllChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All
Delegado (conta pessoal da Microsoft)Delegated (personal Microsoft account) Não suportadoNot Supported
AplicativoApplication ChannelMessage.Read.Group*, ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.AllChannelMessage.Read.Group*, ChannelMessage.Read.All, Group.Read.All, Group.ReadWrite.All

Observação: Permissões marcadas com * usam consentimento específico de recurso.Note: Permissions marked with * use resource-specific consent.

Observação

É necessário solicitar acesso antes de chamar essa API com permissões de aplicativo.Before calling this API with application permissions, you must request access. Para obter detalhes, confira APIs protegidas no Microsoft Teams.For details, see Protected APIs in Microsoft Teams.

Solicitação HTTPHTTP request

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

Parâmetros de consultaQuery parameters

O controle de alterações nas mensagens de canal gera uma série de uma ou mais chamadas de função delta.Tracking changes in channel messages incurs a round of one or more delta function calls. Se você usar qualquer parâmetro de consulta (diferente de $deltatoken e $skiptoken), especifique-o na primeira solicitação delta.If you use any query parameter (other than $deltatoken and $skiptoken), you must specify it in the initial delta request. O Microsoft Graph codifica automaticamente todos os parâmetros especificados na parte do token da URL nextLink ou deltaLink fornecida na resposta.Microsoft Graph automatically encodes any specified parameters into the token portion of the nextLink or deltaLink URL provided in the response.

Você só precisa especificar uma vez antecipadamente os parâmetros de consulta desejados.You only need to specify any query parameters once upfront.

Em solicitações subsequentes, copie e aplique a URL nextLink ou deltaLink da resposta anterior, já que essa URL inclui os parâmetros codificados desejados.In subsequent requests, copy and apply the nextLink or deltaLink URL from the previous response, as that URL already includes the encoded parameters.

Parâmetro de consultaQuery parameter TipoType DescriçãoDescription
$deltatoken stringstring Um token de estado retornado na URL deltaLink da chamada de função delta anterior, indicando a conclusão daquela série de controle de alterações.A state token returned in the deltaLink URL of the previous delta function call, indicating the completion of that round of change tracking. Salve e aplique toda a URL deltaLink, incluindo esse token na primeira solicitação da próxima série de controle de alterações desse conjunto.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 Um token de estado retornado na URLnextLink da chamada de função delta anterior indicando que há mais alterações a serem controladas.A state token returned in the nextLink URL of the previous delta function call, indicating that there are further changes to be tracked.

Parâmetros de consulta OData opcionaisOptional OData query parameters

Os seguintes parâmetros de consulta OData são compatível com esta API:The following OData query parameters are supported by this API:

  • $toprepresenta o número máximo de mensagens a buscar em uma chamada.$top, represents maximum number of messages to fetch in a call. O limite máximo é 50.The upper limit is 50.
  • $skiprepresenta quantas mensagens devem ser ignoradas no início da lista.$skip, represents how many messages to skip at the beginning of the list.
  • $filter permite retornar mensagens que atendem a certos critérios.$filter allows returning messages that meet a certain criteria. A única propriedade que permite a filtragem é lastModifiedDateTime, e somente os operadores gt são compatíveis.The only property that supports filtering is lastModifiedDateTime, and only the gt operator is supported. Por exemplo, o../messages/delta?$filter=lastModifiedDateTime gt 2019-02-27T07:13:28.000z vai buscar todas as mensagens criadas ou alteradas após o período de tempo especificado.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.

Cabeçalhos de solicitaçãoRequest headers

CabeçalhoHeader ValorValue
AutorizaçãoAuthorization {token} de portador. Obrigatório.Bearer {token}. Required.
Content-TypeContent-Type application/jsonapplication/json

Corpo da SolicitaçãoRequest Body

Não forneça um corpo de solicitação para esse método.Do not supply a request body for this method.

RespostaResponse

Se bem sucedido, este método retorna um código de resposta 200 OK e uma coleção de objetos chatMessage no corpo da resposta.If successful, this method returns a 200 OK response code and a collection of chatMessage objects in the response body. A resposta também inclui uma URL nextLink ou uma URL deltaLink.The response also includes a nextLink URL or a deltaLink URL.

ExemplosExamples

Exemplo 1: sincronização inicialExample 1: Initial synchronization

O exemplo a seguir mostra uma série de três solicitações para sincronizar as mensagens num dado canal.The following example shows a series of three requests to synchronize the messages in the given channel. Há cinco mensagens no canal.There are five messages in the channel.

Para economizar tempo, as respostas de exemplo exibem apenas um subconjunto das propriedades para um evento. Em uma chamada real, a maior parte das propriedades dos eventos são retornadas.For brevity, the sample responses show only a subset of the properties for an event. In an actual call, most event properties are returned.

Confira também o que você vai fazer na próxima fase.See also what you'll do in the next round.

Solicitação inicialInitial request

Neste exemplo, as mensagens do canal estão sendo sincronizadas pela primeira vez, portanto a solicitação de sincronização inicial não inclui nenhum token de estado.In this example, the channel messages are being synchronized for the first time, so the initial sync request does not include any state token. Essa rodada mostrará todos os eventos nesse modo de exibição de calendário.This round will return all the events in that calendar view.

A solicitação especifica o cabeçalho de solicitação opcional, odata.top, retornando 2 eventos de cada vez.The request specifies the optional request header, odata.top, returning 2 events at a time.

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

Resposta inicial da solicitaçãoInitial request response

A resposta inclui duas mensagens e um @odata.nextLinkcabeçalho de resposta com um skipToken.The response includes two messages and a @odata.nextLink response header with a skipToken. A URL nextLink indica que há mais mensagens na pasta a serem obtidas.The nextLink URL indicates there are more messages in the channel to get.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.Note: The response object shown here might be shortened for readability. Todas as propriedades serão retornadas de uma chamada real.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"
        }
    ]
}

Segunda solicitaçãoSecond request

A segunda solicitação especifica a URL nextLink retornada na resposta anterior.The second request specifies the nextLink URL returned from the previous response. Observe que não é mais necessário especificar os mesmos parâmetros principais definidos na solicitação inicial, pois o skipToken na URL nextLink os codifica e inclui.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

Resposta da segunda solicitaçãoSecond request response

A segunda resposta retorna as 2 próximas mensagens e um @odata.nextLink cabeçalho de resposta com umskipToken, indicando que há mais mensagens para se obter no canal.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.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.Note: The response object shown here might be shortened for readability. Todas as propriedades serão retornadas de uma chamada real.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"
        }
    ]
}

Terceira solicitaçãoThird request

A terceira solicitação continua a usar a URL nextLink mais recente retornada da última solicitação de sincronização.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

Resposta da terceira solicitaçãoThird request response

A terceira resposta retorna as únicas mensagens restantes no canal e um @odata.deltaLink cabeçalho de resposta com um deltaToken que indica que todas as mensagens no canal foram lidas.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. Salvar e usar a URL deltaLink para consultar novas mensagens a partir desse ponto na próxima rodada.Save and use the deltaLink URL to query for any new messages starting from this point in the next round.

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.Note: The response object shown here might be shortened for readability. Todas as propriedades serão retornadas de uma chamada real.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"
        }
    ]
}

Exemplo 2: recuperar alterações adicionaisExample 2: Retrieving additional changes

Usando o deltaLink da última solicitação na última fase, você poderá obter somente as mensagens que sofreram alteração (por terem sido adicionadas, excluídas ou atualizadas) nesse canal desde então.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. Supondo que você prefira manter o mesmo tamanho máximo de página na resposta, sua solicitação terá um formato semelhante a este :Your request will look like the following, assuming you prefer to keep the same maximum page size in the response:

SolicitaçãoRequest

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

RespostaResponse

**Observação: **o objeto response mostrado aqui pode ser encurtado para legibilidade. Todas as propriedades serão retornadas de uma chamada real.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"
        }
    ]
}