attachment: createUploadSession

Namespace: microsoft.graph

Crie uma sessão de carregamento que permita que um aplicativo carregue de forma iterativa intervalos de um arquivo, de modo a anexar o arquivo ao item Outlook especificado. 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, POST faça uma operação na propriedade de navegação anexos do item Outlook; consulte como fazer isso para uma mensagem ou para um evento.

Como parte da resposta, essa ação retorna uma URL de carregamento que você pode usar em consultas sequenciais subsequentes PUT . Os headers 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 largada durante o carregamento.

Veja a seguir as etapas para anexar um arquivo a um item Outlook usando uma sessão de carregamento:

1. Criar uma sessão de carregamento.
2. Dentro dessa sessão de carregamento, carrega iterativamente intervalos de bytes (até 4 MB cada vez) até que todos os bytes do arquivo tenham sido 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.

Consulte anexar arquivos grandes Outlook mensagens ou eventos para um exemplo.

Dica

Exchange Online permite que os administradores personalizem o limite de tamanho da mensagem para Microsoft 365 caixas de correio, incluindo quaisquer anexos de mensagem. Por padrão, esse limite de tamanho de mensagem é de 35 MB. Saiba como personalizar o tamanho máximo da mensagem para dar suporte a anexos maiores do 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.

Permissões

Uma das seguintes permissões é obrigatória para chamar esta API. Para saber mais, incluindo como escolher permissões, confira Permissões.

Tipo de permissão	Permissões (da com menos para a com mais privilégios)
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 carregamento para anexar um arquivo a um evento:

POST /me/events/{id}/attachments/createUploadSession
POST /users/{id | userPrincipalName}/events/{id}/attachments/createUploadSession

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

POST /me/messages/{id}/attachments/createUploadSession
POST /users/{id | userPrincipalName}/messages/{id}/attachments/createUploadSession

Cabeçalhos de solicitação

Nome	Descrição
Autorização	Portador {token}

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 tiver êxito, este 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 PUT opaca para consultas subsequentes para carregar intervalos de byte do arquivo. Ele contém o token de auth apropriado para consultas PUT subsequentes que expiram por expirationDateTime. Não personalize essa URL.

A propriedade nextExpectedRanges especifica o próximo local de 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 carregamento para adicionar um anexo grande a uma mensagem de rascunho

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

Solicitação

HTTP

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

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

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var attachmentItem = new AttachmentItem
{
    AttachmentType = AttachmentType.File,
    Name = "flower",
    Size = 3483322
};

await graphClient.Me.Messages["{message-id}"].Attachments
    .CreateUploadSession(attachmentItem)
    .Request()
    .PostAsync();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

const uploadSession = {
  AttachmentItem: {
    attachmentType: 'file',
    name: 'flower', 
    size: 3483322
  }
};

await client.api('/me/messages/AAMkADI5MAAIT3drCAAA=/attachments/createUploadSession')
    .post(uploadSession);

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/messages/AAMkADI5MAAIT3drCAAA=/attachments/createUploadSession"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

NSMutableDictionary *payloadDictionary = [[NSMutableDictionary alloc] init];

MSGraphAttachmentItem *attachmentItem = [[MSGraphAttachmentItem alloc] init];
[attachmentItem setAttachmentType: [MSGraphAttachmentType file]];
[attachmentItem setName:@"flower"];
[attachmentItem setSize: 3483322];
payloadDictionary[@"AttachmentItem"] = attachmentItem;

NSData *data = [NSJSONSerialization dataWithJSONObject:payloadDictionary options:kNilOptions error:&error];
[urlRequest setHTTPBody:data];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

AttachmentItem attachmentItem = new AttachmentItem();
attachmentItem.attachmentType = AttachmentType.FILE;
attachmentItem.name = "flower";
attachmentItem.size = 3483322L;

graphClient.me().messages("AAMkADI5MAAIT3drCAAA=").attachments()
    .createUploadSession(AttachmentCreateUploadSessionParameterSet
        .newBuilder()
        .withAttachmentItem(attachmentItem)
        .build())
    .buildRequest()
    .post();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestBody := msgraphsdk.NewAttachmentItemRequestBody()
attachmentItem := msgraphsdk.NewAttachmentItem()
requestBody.SetAttachmentItem(attachmentItem)
attachmentType := "file"
attachmentItem.SetAttachmentType(&attachmentType)
name := "flower"
attachmentItem.SetName(&name)
size := int64(3483322)
attachmentItem.SetSize(&size)
messageId := "message-id"
result, err := graphClient.Me().MessagesById(&messageId).Attachments().CreateUploadSession(message-id).Post(requestBody)

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

PowerShell

Import-Module Microsoft.Graph.Users.Actions

$params = @{
    AttachmentItem = @{
        AttachmentType = "file"
        Name = "flower"
        Size = 3483322
    }
}

# A UPN can also be used as -UserId.
New-MgUserMessageAttachmentUploadSession -UserId $userId -MessageId $messageId -BodyParameter $params

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

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/v1.0/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 carregamento para adicionar um anexo em linha grande a uma mensagem de rascunho

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

Para um anexo em linha, de set isInline property to true and use the contentId property to specify a CID for the attachment as shown below. No corpo da mensagem de rascunho, use o mesmo valor CID para indicar a posição onde 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

HTTP

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

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

C#

GraphServiceClient graphClient = new GraphServiceClient( authProvider );

var attachmentItem = new AttachmentItem
{
    AttachmentType = AttachmentType.File,
    Name = "scenary",
    Size = 7208534,
    IsInline = true,
    ContentId = "my_inline_picture"
};

await graphClient.Me.Messages["{message-id}"].Attachments
    .CreateUploadSession(attachmentItem)
    .Request()
    .PostAsync();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

JavaScript

const options = {
    authProvider,
};

const client = Client.init(options);

const uploadSession = {
  AttachmentItem: {
    attachmentType: 'file',
    name: 'scenary', 
    size: 7208534,
    isInline: true,
    contentId: 'my_inline_picture'
  }
};

await client.api('/me/messages/AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMA=/attachments/createUploadSession')
    .post(uploadSession);

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Objective-C

MSHTTPClient *httpClient = [MSClientFactory createHTTPClientWithAuthenticationProvider:authenticationProvider];

NSString *MSGraphBaseURL = @"https://graph.microsoft.com/v1.0/";
NSMutableURLRequest *urlRequest = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:[MSGraphBaseURL stringByAppendingString:@"/me/messages/AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMA=/attachments/createUploadSession"]]];
[urlRequest setHTTPMethod:@"POST"];
[urlRequest setValue:@"application/json" forHTTPHeaderField:@"Content-Type"];

NSMutableDictionary *payloadDictionary = [[NSMutableDictionary alloc] init];

MSGraphAttachmentItem *attachmentItem = [[MSGraphAttachmentItem alloc] init];
[attachmentItem setAttachmentType: [MSGraphAttachmentType file]];
[attachmentItem setName:@"scenary"];
[attachmentItem setSize: 7208534];
[attachmentItem setIsInline: true];
[attachmentItem setContentId:@"my_inline_picture"];
payloadDictionary[@"AttachmentItem"] = attachmentItem;

NSData *data = [NSJSONSerialization dataWithJSONObject:payloadDictionary options:kNilOptions error:&error];
[urlRequest setHTTPBody:data];

MSURLSessionDataTask *meDataTask = [httpClient dataTaskWithRequest:urlRequest 
    completionHandler: ^(NSData *data, NSURLResponse *response, NSError *nserror) {

        //Request Completed

}];

[meDataTask execute];

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Java

GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

AttachmentItem attachmentItem = new AttachmentItem();
attachmentItem.attachmentType = AttachmentType.FILE;
attachmentItem.name = "scenary";
attachmentItem.size = 7208534L;
attachmentItem.isInline = true;
attachmentItem.contentId = "my_inline_picture";

graphClient.me().messages("AAMkAGUwNjQ4ZjIxLTQ3Y2YtNDViMi1iZjc4LTMA=").attachments()
    .createUploadSession(AttachmentCreateUploadSessionParameterSet
        .newBuilder()
        .withAttachmentItem(attachmentItem)
        .build())
    .buildRequest()
    .post();

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

Go

//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClient(requestAdapter)

requestBody := msgraphsdk.NewAttachmentItemRequestBody()
attachmentItem := msgraphsdk.NewAttachmentItem()
requestBody.SetAttachmentItem(attachmentItem)
attachmentType := "file"
attachmentItem.SetAttachmentType(&attachmentType)
name := "scenary"
attachmentItem.SetName(&name)
size := int64(7208534)
attachmentItem.SetSize(&size)
isInline := true
attachmentItem.SetIsInline(&isInline)
contentId := "my_inline_picture"
attachmentItem.SetContentId(&contentId)
messageId := "message-id"
result, err := graphClient.Me().MessagesById(&messageId).Attachments().CreateUploadSession(message-id).Post(requestBody)

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

PowerShell

Import-Module Microsoft.Graph.Users.Actions

$params = @{
    AttachmentItem = @{
        AttachmentType = "file"
        Name = "scenary"
        Size = 7208534
        IsInline = $true
        ContentId = "my_inline_picture"
    }
}

# A UPN can also be used as -UserId.
New-MgUserMessageAttachmentUploadSession -UserId $userId -MessageId $messageId -BodyParameter $params

Para obter detalhes sobre como adicionar o SDK ao seu projeto e criar uma instância authProvider , consulte a documentação do SDK.

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-"
    ]
}