Anexar arquivos grandes a mensagens ou eventos do OutlookAttach large files to Outlook messages or events

Usando a API do Microsoft Graph, é possível anexar arquivos de até 150 MB a uma mensagem ou item de evento do Outlook.Using the Microsoft Graph API, you can attach files up to 150 MB to an Outlook message or event item. Dependendo do tamanho do arquivo, escolha uma das duas maneiras de anexar o arquivo:Depending on the file size, choose one of two ways to attach the file:

  • Se o tamanho do arquivo for menor que 3 MB, faça uma única POSTAGEM na propriedade de navegação dos anexos do item do Outlook; veja como fazer isso para uma mensagem ou evento.If the file size is under 3 MB, do a single POST on the attachments navigation property of the Outlook item; see how to do this for a message or for an event. A resposta POST bem-sucedida inclui a ID de anexo do arquivo.The successful POST response includes the ID of the file attachment.
  • Se o tamanho do arquivo estiver entre 3 MB e 150 MB, crie uma sessão de carregamento e use o PUT iteradamente para carregar intervalos de bytes do arquivo até que você carregue todo o arquivo.If the file size is between 3MB and 150MB, create an upload session, and iteratively use PUT to upload ranges of bytes of the file until you have uploaded the entire file. Um cabeçalho na resposta PUT finalizada com êxito inclui uma URL com a ID do anexo.A header in the final successful PUT response includes a URL with the attachment ID.

Para anexar vários arquivos a uma mensagem, escolha a abordagem de cada arquivo com base em seu tamanho e anexe-os individualmente.To attach multiple files to a message, choose the approach for each file based on its file size and attach the files individually.

Este artigo ilustra a segunda abordagem passo a passo, criando e usando uma sessão de carregamento para adicionar um anexo de arquivo grande (de tamanho superior a 3MB) a um item do Outlook.This article illustrates the second approach step by step, creating and using an upload session to add a large file attachment (of size over 3MB) to an Outlook item. Cada etapa mostra o código correspondente de uma mensagem e de um evento.Each step shows the corresponding code for a message and for an event. Ao carregar o arquivo inteiro com êxito, o artigo exibe a obtenção de um cabeçalho de resposta contendo uma ID para o anexo do arquivo e, em seguida, o uso dessa ID de anexo para obter o conteúdo bruto do anexo ou metadados do anexo.Upon successfully uploading the entire file, the article shows getting a response header that contains an ID for the file attachment, and then using that attachment ID to get the raw attachment content or attachment metadata.

Importante

Esteja atento a um problema conhecidose você estiver anexando arquivos de grande tamanho a uma mensagem ou evento em uma caixa de correio delegada ou compartilhada.Be aware of a known issue if you're attaching large files to a message or event in a shared or delegated mailbox.

Etapa 1: criar uma sessão de carregamentoStep 1: Create an upload session

Criar uma sessão de carregamento para anexar um arquivo a uma mensagem ou evento.Create an upload session to attach a file to a message or event. Especifique o arquivo no parâmetro de entrada AttachmentItem.Specify the file in the input parameter AttachmentItem.

Uma operação bem-sucedida retorna HTTP 201 Created e uma nova instânciauploadSession, que contém uma URL opaca que você pode usar em operações PUT subseqüentes para carregar partes do arquivo.A successful operation returns HTTP 201 Created and a new uploadSession instance, which contains an opaque URL that you can use in subsequent PUT operations to upload portions of the file. A uploadSession fornece um local de armazenamento temporário onde os bytes do arquivo são salvos até que você tenha carregado o arquivo completo.The uploadSession provides a temporary storage location where the bytes of the file are saved until you have uploaded the complete file.

O objeto uploadSession na resposta também inclui a propriedade nextExpectedRanges, que indica que o local inicial de carregamento deve ser byte 0.The uploadSession object in the response also includes the nextExpectedRanges property, which indicates the initial upload starting location should be byte 0.

PermissõesPermissions

Certifique-se de pedir permissão de Mail.ReadWrite para criar a uploadSession para uma mensagem e Calendars.ReadWrite para um evento.Make sure to request Mail.ReadWrite permission to create the uploadSession for a message, and Calendars.ReadWrite for an event.

A URL opaca, retornada na propriedade uploadUrl do novo uploadSession é pré-autenticada e contém o token de autorização apropriado para consultas PUT subsequentes no domínio https://outlook.office.com.The opaque URL, returned in the uploadUrl property of the new uploadSession, is pre-authenticated and contains the appropriate authorization token for subsequent PUT queries in the https://outlook.office.com domain. Esse token expira por expirationDateTime.That token expires by expirationDateTime. Não Personalize essa URL para as operações PUT.Do not customize this URL for the PUT operations.

Exemplo: criar uma sessão de carregamento para uma mensagemExample: create an upload session for a message

SolicitaçãoRequest

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

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

RespostaResponse

O exemplo de resposta a seguir mostra o recurso uploadSession retornado para a mensagem.The following example response shows the uploadSession resource returned for the message.

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/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0tAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI",
    "expirationDateTime": "2019-09-25T01:09:30.7671707Z",
    "nextExpectedRanges": [
        "0-"
    ]
}

Exemplo: criar uma sessão de carregamento para uma eventoExample: create an upload session for an event

SolicitaçãoRequest

POST https://graph.microsoft.com/v1.0/me/events/AAMkADU5CCmSAAA=/attachments/createUploadSession
Content-type: application/json

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

RespostaResponse

O exemplo de resposta a seguir mostra o recurso uploadSession retornado para o evento.The following example response shows the uploadSession resource returned for the event.

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/v2.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/AttachmentSessions('AAMkADU5RpAACJlCs8AAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIBtw",
    "expirationDateTime": "2020-02-22T02:46:56.7410786Z",
    "nextExpectedRanges": [
        "0-"
    ]
}

Etapa 2: usar a sessão de carregamento para carregar um intervalo de bytes do arquivoStep 2: Use the upload session to upload a range of bytes of the file

Para carregar o arquivo, ou uma parte do arquivo, faça uma solicitação PUT à URL retornada na etapa 1 na propriedade uploadUrl do recurso uploadSession.To upload the file, or a portion of the file, make a PUT request to the URL returned in step 1 in the uploadUrl property of the uploadSession resource. Você pode carregar todo o arquivo ou dividi-lo em vários intervalos de bytes.You can upload the entire file, or split the file into multiple byte ranges. Para melhorar o desempenho, mantenha cada intervalo de bytes com menos de 4 MB.For better performance, keep each byte range less than 4 MB.

Especifique os cabeçalhos e corpo da solicitação conforme é descrito abaixo.Specify request headers and request body as described below.

Cabeçalhos de solicitaçãoRequest headers

NomeName TipoType DescriçãoDescription
Content-LengthContent-Length Int32Int32 O número de bytes sendo carregados nesta operação.The number of bytes being uploaded in this operation. Para melhorar o desempenho, mantenha o limite superior do número de bytes para cada operação PUT em 4 MB.For better performance, keep the upper limit of the number of bytes for each PUT operation to 4 MB. Obrigatório.Required.
Intervalo de conteúdoContent-Range Cadeia de CaracteresString O intervalo de bytes baseado em 0 do arquivo que está sendo carregado nesta operação, expresso no formato bytes {start}-{end}/{total}.The 0-based byte range of the file being uploaded in this operation, expressed in the format bytes {start}-{end}/{total}. Obrigatório.Required.
Content-TypeContent-Type Cadeia de CaracteresString O tipo MIME.The MIME type. Especifiqueapplication/octet-stream.Specify application/octet-stream. Obrigatório.Required.

Não especifique um cabeçalho da solicitaçãoAuthorization.Do not specify an Authorization request header. A consulta PUT usa uma URL pré-existente da propriedade uploadUrl, que permite o acesso ao domínio https://outlook.office.com.The PUT query uses a pre-authenticated URL from the uploadUrl property, that allows access to the https://outlook.office.com domain.

Corpo da solicitaçãoRequest body

Especificar os bytes reais do arquivo a ser anexado, que estão no intervalo de local especificado pelo cabeçalho da solicitaçãoContent-Range.Specify the actual bytes of the file to be attached, that are in the location range specified by the Content-Range request header.

RespostaResponse

Um carregamento bem-sucedido retorna HTTP 200 OK e um objeto uploadSession.A successful upload returns HTTP 200 OK and an uploadSession object. Observe o seguinte no objeto de resposta:Note the following in the response object:

  • A propriedade ExpirationDateTime indica a data/hora de vencimento para o token de autenticação inserido no valor da propriedade uploadUrl.The ExpirationDateTime property indicates the expiration date/time for the auth token embedded in the uploadUrl property value. Essa data/hora de vencimento permanece a mesma que foi retornada pela uploadSession inicial na etapa 1.This expiration date/time remains the same as returned by the initial uploadSession in step 1.
  • NextExpectedRanges especifica o próximo local do byte para começar o carregamento a partir de "NextExpectedRanges":["2097152"], por exemplo.The NextExpectedRanges specifies the next byte location to start uploading from, for example, "NextExpectedRanges":["2097152"]. Você deve carregar os bytes em um arquivo na ordem.You must upload bytes in a file in order.
  • A propriedade uploadUrl não é retornada explicitamente, pois todas as operações PUT de uma sessão de carregamento usam a mesma URL retornada ao criar a sessão (etapa 1).The uploadUrl property is not explicitly returned, because all PUT operations of an upload session use the same URL returned when creating the session (step 1).

Exemplo: primeiro carregamento na mensagemExample: first upload to the message

SolicitaçãoRequest

PUT https://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0tAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI
Content-Type: application/octet-stream
Content-Length: 2097152
Content-Range: bytes 0-2097151/3483322

{
  <bytes 0-2097151 of the file to be attached, in binary format>
}

RespostaResponse

O exemplo de resposta a seguir mostra na propriedade NextExpectedRanges o início do próximo intervalo de bytes que o servidor espera.The following example response shows in the NextExpectedRanges property the start of the next byte range that the server expects.

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

{
  "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Users('a8e8e219-4931-95c1-b73d-62626fd79c32%4072aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA%3D')/AttachmentSessions/$entity",
  "ExpirationDateTime":"2019-09-25T01:09:30.7671707Z",
  "NextExpectedRanges":["2097152"]
}

Exemplo: primeiro carregamento na eventoExample: first upload to the event

SolicitaçãoRequest

PUT https://outlook.office.com/api/v2.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/AttachmentSessions('AAMkADU5RpAACJlCs8AAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIBtw
Content-Type: application/octet-stream
Content-Length: 2097152
Content-Range: bytes 0-2097151/3483322

{
  <bytes 0-2097151 of the file to be attached, in binary format>
}

RespostaResponse

O exemplo de resposta a seguir mostra na propriedade NextExpectedRanges o início do próximo intervalo de bytes que o servidor espera.The following example response shows in the NextExpectedRanges property the start of the next byte range that the server expects.

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

{
    "@odata.context":"https://outlook.office.com/api/v2.0/$metadata#Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69%4098a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA%3D')/AttachmentSessions/$entity",
    "ExpirationDateTime":"2020-02-22T02:46:56.7410786Z",
    "NextExpectedRanges":["2097152"]
}

Etapa 3: continuar carregando intervalos de bytes até que todo o arquivo tenha sido carregadoStep 3: Continue uploading byte ranges until the entire file has been uploaded

Após o carregamento inicial na etapa 2, continue a carregar a parte restante do arquivo, usando uma solicitação PUT semelhante, conforme descrito na etapa 2, antes que você atinja a data/hora de vencimento da sessão.Following the initial upload in step 2, continue to upload the remaining portion of the file, using a similar PUT request as described in step 2, before you reach the expiration date/time for the session. Use a coleção NextExpectedRanges para determinar onde começar o próximo intervalo de bytes a ser carregado.Use the NextExpectedRanges collection to determine where to start the next byte range to upload. É possível ver vários intervalos especificados, indicando partes do arquivo que o servidor ainda não recebeu.You may see multiple ranges specified, indicating parts of the file that the server has not yet received. Isso é útil quando você precisa retomar uma transferência que foi interrompida, e seu cliente não tem certeza sobre o estado no serviço.This is useful if you need to resume a transfer that was interrupted and your client is unsure of the state on the service.

Quando o último byte do arquivo for carregado com êxito, a operação de PUT final retornará HTTP 201 Created e um cabeçalho Location que indica a URL para o anexo de arquivo no domínio https://outlook.office.com.Once the last byte of the file has been successfully uploaded, the final PUT operation returns HTTP 201 Created and a Location header that indicates the URL to the file attachment in the https://outlook.office.com domain. Você pode obter a ID do anexo na URL e salvá-la para uso posterior.You can get the attachment ID from the URL and save it for later use. Dependendo do cenário, você pode usar essa ID para obter os metadados do anexoou remover o anexo do item do Outlook usando o ponto de extremidade do Microsoft Graph.Depending on your scenario, you can use that ID to get the metadata of the attachment, or remove the attachment from the Outlook item using the Microsoft Graph endpoint.

Os exemplos a seguir mostram o carregamento do último intervalo de bytes do arquivo na mensagem e no evento das etapas anteriores.The following examples show uploading the last byte range of the file to the message and to the event in the preceding steps.

Exemplo: último carregamento na mensagemExample: final upload to the message

SolicitaçãoRequest

PUT https://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0tAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI
Content-Type: application/octet-stream
Content-Length: 1386170
Content-Range: bytes 2097152-3483321/3483322

{
  <bytes 2097152-3483321 of the file to be attached, in binary format>
}

RespostaResponse

O exemplo de resposta a seguir mostra um cabeçalho de resposta de Location onde você pode salvar a ID do anexo (AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=) para uso posterior.The following example response shows a Location response header from which you can save the attachment ID (AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=) for later use.

HTTP/1.1 201 Created

Location: https://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/Attachments('AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=')
Content-Length: 0

Exemplo: último carregamento no eventoExample: final upload to the event

SolicitaçãoRequest

PUT https://outlook.office.com/api/v2.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/AttachmentSessions('AAMkADU5RpAACJlCs8AAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIBtw
Content-Type: application/octet-stream
Content-Length: 1386170
Content-Range: bytes 2097152-3483321/3483322

{
  <bytes 2097152-3483321 of the file to be attached, in binary format>
}

RespostaResponse

O exemplo de resposta a seguir mostra um cabeçalho de resposta de Location onde você pode salvar a ID do anexo (AAMkADU5CCmSAAANZAlYPeyQByv7Y=) para uso posterior.The following example response shows a Location response header from which you can save the attachment ID (AAMkADU5CCmSAAANZAlYPeyQByv7Y=) for later use.

HTTP/1.1 201 Created

Location: https://outlook.office.com/api/v2.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/Attachments('AAMkADU5CCmSAAANZAlYPeyQByv7Y=')
Content-Length: 0

Etapa 4 (opcional): obter o arquivo em anexo do item do OutlookStep 4 (optional): Get the file attachment from the Outlook item

Como sempre, obter um anexo a partir de um item do Outlook não é tecnicamente limitado pelo tamanho do anexo.As always, getting an attachment from an Outlook item is not technically limited by attachment size.

No entanto, obter um anexo de arquivo grande no formato base64-encoded afeta o desempenho da API.However, getting a large file attachment in base64-encoded format affects API performance. Se você espera um anexo grande:If you expect a large attachment:

Exemplo: obter o arquivo bruto anexado ao eventoExample: Get the raw file attached to the event

Seguindo o exemplo de evento e utilizando a ID do anexo retornada no cabeçalho de Location da etapa anterior, a solicitação de exemplo nesta seção mostra o uso de um parâmetro $value para obter os dados de conteúdo bruto do anexo.Following the event example and using the attachment ID returned in the Location header of the previous step, the example request in this section shows using a $value parameter to get the attachment raw content data.

PermissõesPermissions

Use a permissão delegada ou de aplicativo com menos privilégios, Calendars.Read, conforme apropriado, para esta operação.Use the least privileged delegated or application permission, Calendars.Read, as appropriate, for this operation. Para obter mais informações, confira permissões de calendário.For more information, see calendar permissions.

SolicitaçãoRequest

GET https://graph.microsoft.com/v1.0/Users('d3b9214b-dd8b-441d-b7dc-c446c9fa0e69@98a79ebe-74bf-4e07-a017-7b410848cb32')/Events('AAMkADU5CCmSAAA=')/Attachments('AAMkADU5CCmSAAANZAlYPeyQByv7Y=')/$value

RespostaResponse

HTTP/1.1 200 OK
content-length: 3483322
Content-type: image/jpeg

{Raw bytes of the file}

Exemplo: obter os metadados do arquivo anexado à mensagemExample: Get the metadata of the file attached to the message

Seguindo o exemplo da mensagem, a solicitação de exemplo de solicitação nesta seção mostra o uso de um parâmetro $select para obter alguns dos metadados de um anexo de arquivo em uma mensagem, excluindo o contentBytes.Following the message example, the example request in this section shows using a $select parameter to get some of the metadata of a file attachment on a message, excluding contentBytes.

PermissõesPermissions

Use a permissão delegada ou de aplicativo com menos privilégios, Mail.Read, conforme apropriado, para esta operação.Use the least privileged delegated or application permission, Mail.Read, as appropriate, for this operation. Saiba mais em permissões de correio.For more information, see mail permissions.

SolicitaçãoRequest

GET https://graph.microsoft.com/api/v1.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/Attachments('AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=')?$select=lastModifiedDateTime,name,contentType,size,isInline

RespostaResponse

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

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#users('a8e8e219-4931-95c1-b73d-62626fd79c32%4072aa88bf-76f0-494f-91ab-2d7cd730db47')/messages('AAMkADI5MAAIT3drCAAA%3D')/attachments/$entity",
    "@odata.type": "#microsoft.graph.fileAttachment",
    "@odata.mediaContentType": "image/jpeg",
    "id": "AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=",
    "lastModifiedDateTime": "2019-09-24T23:27:43Z",
    "name": "flower",
    "contentType": "image/jpeg",
    "size": 3640066,
    "isInline": false
}

Alternativa: cancelar a sessão de carregamentoAlternative: Cancel the upload session

Em qualquer momento antes da sessão de carregamento expirar, se for preciso cancelar o carregamento, você poderá usar a mesma URL opaca inicial para excluir a sessão de carregamento.At any point of time before the upload session expires, if you have to cancel the upload, you can use the same initial opaque URL to delete the upload session. Uma operação bem-sucedida retorna HTTP 204 No Content.A successful operation returns HTTP 204 No Content.

PermissõesPermissions

Como a URL opaca inicial é pré-autenticada e contém o token de autorização apropriado para consultas subsequentes para essa sessão de carregamento, não especifique um cabeçalho de solicitação de autorização para essa operação.Because the initial opaque URL is pre-authenticated and contains the appropriate authorization token for subsequent queries for that upload session, do not specify an Authorization request header for this operation.

Exemplo: cancelar a sessão de carregamento da mensagemExample: cancel the upload session for the message

SolicitaçãoRequest

DELETE https://outlook.office.com/api/v2.0/Users('a8e8e219-4931-95c1-b73d-62626fd79c32@72aa88bf-76f0-494f-91ab-2d7cd730db47')/Messages('AAMkADI5MAAIT3drCAAA=')/AttachmentSessions('AAMkADI5MAAIT3k0tAAA=')?authtoken=eyJhbGciOiJSUzI1NiIsImtpZCI6IktmYUNIUlN6bllHMmNI

RespostaResponse

HTTP/1.1 204 No content

ErrosErrors

ErrorAttachmentSizeShouldNotBeLessThanMinimumSizeErrorAttachmentSizeShouldNotBeLessThanMinimumSize

Este erro é devolvido ao tentar criar uma sessão de upload para anexar um arquivo menor que 3 MB.This error is returned when attempting to create an upload session to attach a file smaller than 3 MB. Se o tamanho do arquivo for menor que 3 MB, faça uma única POSTAGEM na propriedade de navegação dos anexos da mensagem ou do evento.If the file size is under 3 MB, you should do a single POST on the attachments navigation property of the message or of the event. A resposta POST bem-sucedida inclui a ID do arquivo anexado à mensagem.The successful POST response includes the ID of the file attached to the message.