Partilhar via


anexo: createUploadSession

Namespace: microsoft.graph

Importante

As APIs na versão /beta no Microsoft Graph estão sujeitas a alterações. Não há suporte para o uso dessas APIs em aplicativos de produção. Para determinar se uma API está disponível na v1.0, use o seletor Versão.

Crie uma sessão de upload que permita que um aplicativo carregue iterativamente intervalos de um arquivo, de modo a anexar o arquivo a um item do Outlook. O item pode ser uma mensagem ou evento.

Use essa abordagem para anexar um arquivo se o tamanho do arquivo estiver entre 3 MB e 150 MB. Para anexar um arquivo menor que 3 MB, faça uma POST operação na propriedade de navegação anexos do item do Outlook; confira como fazer isso para uma mensagem ou para um evento.

Como parte da resposta, essa ação retorna uma URL de upload que você pode usar em consultas sequenciais PUT subsequentes. Os cabeçalhos de solicitação para cada PUT operação permitem especificar o intervalo exato de bytes a serem carregados. Isso permite que a transferência seja retomada, caso a conexão de rede seja descartada durante o upload.

A seguir estão as etapas para anexar um arquivo a um item do Outlook usando uma sessão de upload:

  1. Crie uma sessão de upload.
  2. Nessa sessão de carregamento, carregue iterativamente intervalos de bytes (até 4 MB cada vez) até que todos os bytes do arquivo sejam carregados e o arquivo seja anexado ao item especificado.
  3. Salve a ID do anexo para acesso futuro.
  4. Opcional: exclua a sessão de carregamento.

Confira anexar arquivos grandes a mensagens ou eventos do Outlook para obter um exemplo.

Dica

Exchange Online permite que os administradores personalizem o limite de tamanho da mensagem para caixas de correio do Microsoft 365, incluindo todos os anexos de mensagem. Por padrão, esse limite de tamanho da mensagem é de 35 MB. Descubra como personalizar o tamanho máximo da mensagem para dar suporte a anexos maiores que o limite padrão para seu locatário.

Importante

Esteja ciente de um problema conhecido se você estiver anexando um arquivo grande a uma mensagem ou evento em uma caixa de correio compartilhada ou delegada.

Essa API está disponível nas seguintes implantações nacionais de nuvem.

Serviço global Governo dos EUA L4 GOVERNO DOS EUA L5 (DOD) China operada pela 21Vianet

Permissões

Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões privilegiadas mais altas
Delegado (conta corporativa ou de estudante) Calendars.ReadWrite Mail.ReadWrite
Delegado (conta pessoal da Microsoft) Calendars.ReadWrite Mail.ReadWrite
Aplicativo Calendars.ReadWrite Mail.ReadWrite

Solicitação HTTP

Para criar uma sessão de upload para anexar um arquivo a um evento:

POST /me/events/{id}/attachments/createUploadSession

Para criar uma sessão de upload para anexar um arquivo a uma mensagem:

POST /me/messages/{id}/attachments/createUploadSession

Cabeçalhos de solicitação

Nome Descrição
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.

Corpo da solicitação

Forneça um objeto JSON com os seguintes parâmetros no corpo da solicitação.

Parâmetro Tipo Descrição
AttachmentItem attachmentItem Representa atributos do item a ser carregado e anexado. No mínimo, especifique o tipo de anexo (file), um nome e o tamanho do arquivo.

Resposta

Se for bem-sucedido, esse método retornará um 201 Created código de resposta e um novo objeto uploadSession no corpo da resposta.

Observação:

A propriedade uploadUrl retornada como parte do objeto de resposta uploadSession é uma URL opaca para consultas subsequentes PUT para carregar intervalos de bytes do arquivo. Ele contém o token de auth apropriado para consultas subsequentes PUT que expiram por expirationDateTime. Não personalize essa URL.

A propriedade nextExpectedRanges especifica o próximo local do byte de arquivo a ser carregado, por exemplo, "NextExpectedRanges":["2097152"]. Você deve carregar os bytes em um arquivo na ordem.

Exemplos

Exemplo 1: criar uma sessão de upload para adicionar um anexo grande a uma mensagem de rascunho

O exemplo a seguir mostra como criar uma sessão de upload que você pode usar em operações de carregamento de arquivo subsequentes para a mensagem especificada.

Solicitação

POST https://graph.microsoft.com/beta/me/messages/AAMkADI5MAAIT3drCAAA=/attachments/createUploadSession
Content-type: application/json

{
  "AttachmentItem": {
    "attachmentType": "file",
    "name": "flower",
    "size": 3483322
  }
}

Resposta

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.uploadSession",
    "uploadUrl": "https://outlook.office.com/api/beta/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0uAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI",
    "expirationDateTime": "2019-09-25T01:09:30.7671707Z",
    "nextExpectedRanges": [
        "0-"
    ]
}

Exemplo 2: criar uma sessão de upload para adicionar um anexo de linha grande a uma mensagem de rascunho

O exemplo a seguir mostra como criar uma sessão de upload que pode ser usada para adicionar um anexo embutido grande a uma mensagem de rascunho.

Para um anexo embutido, defina a propriedade isInline para true e use a propriedade contentId para especificar um CID para o anexo, conforme mostrado abaixo. No corpo da mensagem de rascunho, use o mesmo valor CID para indicar a posição em que você deseja incluir o anexo usando uma marca de referência HTML CID, por exemplo <img src="cid:my_inline_picture">. Ao carregar o arquivo com êxito, a mensagem renderizada incluirá o anexo como parte do corpo da mensagem no local especificado.

Solicitação

POST https://graph.microsoft.com/beta/me/messages/AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMA=/attachments/createUploadSession
Content-type: application/json

{
  "AttachmentItem": {
    "attachmentType": "file",
    "name": "scenary",
    "size": 7208534,
    "isInline": true,
    "contentId": "my_inline_picture"
  }
}

Resposta

Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.uploadSession",
    "uploadUrl": "https://outlook.office.com/api/gv1.0/users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/messages('AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMA=')/AttachmentSessions('AAMkAGUwNjQ4ZjIxLTAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IjFTeXQ1bXdXYVh5UFJ",
    "expirationDateTime": "2021-12-27T14:20:12.9708933Z",
    "nextExpectedRanges": [
        "0-"
    ]
}