Enviar solicitações REST do Outlook em lotes (versão 2.0)

Aplica-se ao: Exchange Online | Office 365 | Hotmail.com | Live.com | MSN.com | Outlook.com | Passport.com

O envio em lote permite que você coloque várias solicitações REST do Outlook em uma única solicitação HTTP em lote, reduzindo o número de conexões HTTP e a sobrecarga. As solicitações em um lote acessam os dados do usuário conectado, protegidos pelo Active Directory do Azure no Office 365 ou em uma conta da Microsoft (Hotmail.com, Live.com, MSN.com, Outlook.com ou Passport.com).

Observação

Para simplificar a referência, o restante deste artigo usa o Outlook.com para incluir esses domínios de conta da Microsoft.

Não tem interesse na v2.0 da API? Na tabela de conteúdo à esquerda, vá para a seção Referência da API REST do Office 365 e selecione a versão desejada.

Visão geral

Uma solicitação REST requer uma conexão HTTP entre o cliente e o servidor, o que acarreta uma certa sobrecarga. O envio em lote permite reduzir a sobrecarga de conexão ao combinar várias chamadas da API REST para o mesmo contexto em uma única solicitação POST HTTP para o ponto de extremidade de $lote.

Por exemplo, você pode combinar chamadas de API para o contexto me como este:

POST https://outlook.office.com/api/v2.0/me/$batch

Uma solicitação em lote pode incluir até 20 chamadas individuais da API REST, que podem ser operações de consulta de dados (por exemplo, GET) ou alterações (por exemplo, POST). Você pode especificar um cabeçalho Preferir para que o lote continue mesmo quando uma ou mais chamadas REST falharem.

O envio em lote é útil principalmente na sincronização de grandes quantidades de dados. Chamadas de API no mesmo lote podem acessar recursos diferentes, como mensagens e eventos, que pertencem à mesma caixa de correio.

Se você precisar fazer mais de 20 chamadas ou se a ordem de conclusão das chamadas for importante, use várias solicitações em lote.

Exemplo

Um exemplo simples ilustra melhor o envio em lote. A solicitação em lote a seguir coloca duas chamadas da API REST do Outlook em um único lote para o contexto me:

1. Obter todos os eventos do usuário conectado.
2. POST e envie uma mensagem.

Solicitação em lote

POST https://outlook.office.com/api/v2.0/me/$batch HTTP/1.1

Authorization: Bearer aGFwcHlnQGRr==
Host: outlook.office.com
Content-Type: multipart/mixed; boundary=batch_myBatchId


--batch_myBatchId
Content-Type: application/http
Content-Transfer-Encoding: binary

GET /api/v2.0/me/events?$select=subject,organizer HTTP/1.1

--batch_myBatchId
Content-Type: application/http
Content-Transfer-Encoding: binary

POST /api/v2.0/me/sendmail HTTP/1.1
Content-Type: application/json

{
  "Message": {
    "Subject": "Meet for lunch?",
    "Body": {
      "ContentType": "Text",
      "Content": "The new cafeteria is open."
    },
    "ToRecipients": [
      {
        "EmailAddress": {
          "Address": "rufus@contoso.com"
        }
      }
    ]
  }
}
 
--batch_myBatchId--

Observação

No exemplo anterior, que tem uma operação POST no final do lote, no momento, é necessária uma nova linha depois do último delimitador de lote --batch_{batchId}--. Veja mais notas de formatação para corpos de solicitação em lote.

Resposta em lote

A resposta em lote inclui códigos e corpos de resposta separados, quando aplicável, para a solicitação em lote e as chamadas individuais.

HTTP/1.1 200 OK
Content-Type: multipart/mixed; boundary=batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Length: 786

--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 200 OK
OData-Version: 4.0
Content-Type: application/json;odata.metadata=minimal;odata.streaming=true;IEEE754Compatible=false;charset=utf-8

{
    "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Me/Events(Subject,Organizer)",
    "value":[
        {
            "@odata.id":"https://outlook.office.com/api/v2.0/Users('cd209b0b-3f83-4c35-82d2-d88a61820480@8b5d41d8-b1af-495e-b871-8bbd867ba67a')/Events('AAMkAGI1AAAt9AHkAAA=')",
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAALfZeSA==\"",
            "Id":"AAMkAGI1AAAt9AHkAAA=",
            "Subject":"Let's go for lunch",
            "Organizer":{
                "EmailAddress":{
                    "Name":"Dana Swope",
                    "Address":"danas@contoso.onmicrosoft.com"
                }
            }
        },
        {
            "@odata.id":"https://outlook.office.com/api/v2.0/Users('cd209b0b-3f83-4c35-82d2-d88a61820480@8b5d41d8-b1af-495e-b871-8bbd867ba67a')/Events('AAMkAGI1AAAtCq6LAAA=')",
            "@odata.etag":"W/\"ZlnW4RIAV06KYYwlrfNZvQAALQzodA==\"",
            "Id":"AAMkAGI1AAAtCq6LAAA=",
            "Subject":"Prep for customer visit",
            "Organizer":{
                "EmailAddress":{
                    "Name":"Dana Swope",
                    "Address":"danas@contoso.onmicrosoft.com"
                }
            }
        }
    ]
}
--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 202 Accepted

--batchresponse_caad32b6-3fa6-4346-94d0-ee98e067318a--

URL de ponto de extremidade

Você pode fazer um POST no ponto de extremidade $batch para um dos dois contextos:

• Para o usuário conectado me:

  POST https://outlook.office.com/api/v2.0/me/$batch HTTP/1.1
  

• Para um usuário específico, em que user_id pode ser uma identificação de usuário ou endereço de email do usuário:

  POST https://outlook.office.com/api/v2.0/users('{user_id}')/$batch
  

Depois de estabelecer o contexto na solicitação POST para o ponto de extremidade do $batch, todas as chamadas da API REST incluídas na mesma solicitação em lote devem se aplicar ao mesmo contexto.

Importante

• Se a sua solicitação em lote for para um usuário específico, certifique-se de fazer referência ao usuário de maneira consistente em todo o conjunto de solicitações em lote. Ou seja, use somente .../users('{user_id}') ou .../users/'{user_id}', mas não ambos.
• Ao usar a URL da raiz https://outlook.office.com, para ter um ótimo desempenho, adicione um cabeçalho x-AnchorMailbox e defina-o para o endereço de email do usuário.
• Você deve tratar o caso em que a caixa de correio de um usuário do Outlook.com ainda não foi habilitada para a API REST do Outlook - verifique os códigos de erro MailboxNotEnabledForRESTAPI e MailboxNotSupportedForRESTAPI. Veja mais informações aqui.

Observação

Notas para desenvolvedores na China

• Se você estiver desenvolvendo aplicativos para o Office 365 na China, deve continuar a usar os pontos de extremidade da API do Office 365 para a China.
• Se você está criando aplicativos para o Outlook.com na China, deve usar a Versão prévia do modelo de aplicativo v2 e o seguinte ponto de extremidade REST do Outlook: https://outlook.office.com/api/{version}

Versão da API

O envio em lote foi promovido da versão prévia para o status de Disponibilidade Geral (GA). Há suporte nas versões v2.0 e beta da API REST do Outlook.

Você deve especificar o mesmo host e versão na solicitação em lote como nas chamadas REST no lote.

Usuário de destino

Você pode agrupar as chamadas da API REST do Outlook para a mesma caixa de correio em um lote. A caixa de correio pode estar no Office 365 ou no Outlook.com. A tentativa de acessar mais de uma caixa de correio em um conjunto de solicitações em lote resulta em uma exceção.

Autenticação

Semelhante ao envio de chamadas API REST do Outlook como solicitações individuais, você deve incluir um token de acesso válido em um cabeçalho de solicitação de Autorização. Se você especificar esse cabeçalho para a solicitação em lote, o token de acesso deverá fornecer a permissão necessária para todas as chamadas nesse lote. Opcionalmente, você pode especificar um token de acesso para uma chamada específica no lote, se essa chamada exigir um token de acesso diferente.

Para obter um token de acesso você deve ter registrado e identificado o seu aplicativo e obtido a autorização adequada. Saiba mais sobre algumas opções simplificadas de registro e autorização. Lembre-se disso enquanto aprende mais sobre solicitações em lote.

Cabeçalhos de solicitações em lote

Inclua os seguintes cabeçalhos para cada solicitação em lote:

Host: outlook.office.com
Content-Type: multipart/mixed; boundary=batch_<batchId> 

em que {batchId} identifica um lote e é usado para delimitar solicitações dentro do lote. Pode ser um GUID ou uma sequência de caracteres de distinção.

Você pode incluir outros cabeçalhos quando for apropriado. Exceto para cabeçalhos relacionados a conteúdo, como Content-Type, os cabeçalhos na solicitação em lote geralmente se aplicam a todas as operações no lote. Se você especificar um cabeçalho na solicitação em lote e em uma operação específica no lote, o último terá precedência e se aplicará a essa operação.

Corpo da solicitação em lote

Inicie cada operação dentro de um lote com as seguintes linhas de cabeçalho:

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

Encerre a última operação no lote com isto:

--batch_{batchId}--
 

Formatação de um corpo da solicitação em lote

Observe os seguintes requisitos de formatação, caso contrário, sua solicitação em lote poderá falhar ou não retornar as respostas esperadas:

• Certifique-se de ter uma nova linha adicional antes de um delimitador de limite de lote, conforme mostrado no corpo da solicitação a seguir que possui duas operações GET em lote.
• Em particular, se você tiver uma solicitação POST no final de um lote semelhante à primeira solicitação em lote de exemplo, verifique se há uma nova linha depois do último delimitador de lote --batch_{batchId}--.

Você pode ver mais exemplos de corpos de solicitação em lote em Processamento em lote (OData versão 3.0).

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

GET  /api/v2.0/me/messages    HTTP/1.1

--batch_{batchId} 
Content-Type: application/http 
Content-Transfer-Encoding: binary 

GET  /api/v2.0/me/events    HTTP/1.1

--batch_{batchId}--
 

Operações em lote

Você pode especificar até 20 operações em uma solicitação em lote.

Uma operação em um lote pode ser uma solicitação de consulta de dados, modificação, ação ou invocação de função. Embora não seja necessário repetir URLs inteiras e indicar todos os cabeçalhos para cada operação no lote, inclua cabeçalhos e corpos de solicitação específicos se eles forem necessários para uma operação.

Formatos suportados de solicitações em um lote

Como mencionado acima, o host, a versão e o contexto devem permanecer consistentes por todo um conjunto de solicitações em lote. As solicitações incluídas no mesmo lote podem ser uma mistura de qualquer um dos três formatos a seguir. Para os exemplos abaixo, suponha que a solicitação POST para o ponto de extremidade $batch tenha esta aparência:

POST https://outlook.office.com/api/v2.0/me/$batch HTTP/1.1

URL absoluta

Inclua o host, a versão e o contexto na URL. Por exemplo:

GET https://outlook.office.com/api/v2.0/me/messages?$select=subject,sender HTTP/1.1 

URL relativa ao host

Inclua uma URL relativa ao host especificado na solicitação em lote. Embora você não repita o host em cada solicitação em lote, inclua a versão e o contexto. Por exemplo:

GET /api/v2.0/me/messages?$select=subject,sender HTTP/1.1

URL relativa ao lote

Nesse formato, você não repete o host, a versão e o contexto na solicitação em lote. Por exemplo:

GET messages?$select=subject,sender HTTP/1.1

Processamento de uma solicitação em lote

Uma solicitação em lote é processada por conta própria como uma solicitação e retorna seu próprio código de resposta. Uma solicitação em lote bem formada com cabeçalhos corretos retorna HTTP 200 OK. No entanto, isso não significa que todas as solicitações no lote foram bem-sucedidas.

Cada solicitação no corpo da solicitação em lote é, por sua vez, processada separadamente e retorna seu próprio código de resposta e corpos de resposta e mensagens de erro.

O servidor pode executar operações dentro de um lote em qualquer ordem. Se você precisar executar operações em uma ordem específica, não deverá colocá-las na mesma solicitação em lote. Em vez disso, envie uma operação sozinha e aguarde a resposta antes de enviar a próxima.

Por padrão, o processamento é interrompido na primeira operação que retorna um erro. Você pode especificar o seguinte cabeçalho para que o processamento ignore o erro e continue com a próxima operação no lote:

Prefer: odata.continue-on-error

Próximas etapas

Se você estiver pronto para começar a criar um aplicativo ou apenas quiser aprender mais, temos tudo o que você precisa.

• Comece com as APIs REST de Email, Calendário e Contatos.
• Quer exemplos? Nós temos.

Se preferir, aprenda mais sobre como usar a plataforma do Office 365:

• API REST do Outlook no Centro de Desenvolvimento do Outlook
• Visão geral sobre desenvolvimento na plataforma do Office 365
• Autenticação de aplicativo do Office 365 e autorização de recursos
• Registre manualmente seu aplicativo com o AD do Azure para que ele possa acessar as APIs do Office 365
• Referência de APIs REST de Email
• Referência de APIs REST do Calendário
• Referência de APIs REST de contatos
• API REST de Atribuições (versão prévia)
• Referência de recurso para as APIs REST de Email, Calendário, Contatos e Tarefa
• Referência da API REST de Extensões de Dados do Office 365
• Referência da API REST Pessoas
• Referência da API REST de Notificações
• Referência da API REST da Foto do Usuário