Adjuntar archivos a una tarea de To Do

Con la API de To Do en Microsoft Graph, puede adjuntar archivos de hasta 25 MB a una todoTask. Según el tamaño del archivo, elija una de las dos formas de adjuntar el archivo:

• Para adjuntar archivos de cualquier tamaño, cree una sesión de carga e itere solicitudes PUT para cargar partes del archivo hasta cargarlo entero. El encabezado de la respuesta PUT final correcta incluye una dirección URL con el ID. de datos adjuntos.
• Si el tamaño del archivo es inferior a 3 MB, use el método POST una vez en la propiedad de navegación de datos adjuntos de una todoTask; vea cómo hacerlo para una tarea. Si la respuesta POST es correcta, incluirá el ID. del archivo adjunto.

En este artículo se muestra el primer enfoque. Aprenderá paso a paso cómo crear y usar una sesión de carga para agregar datos adjuntos de archivo a una tarea.

Paso 1: crear una sesión de carga

Cree una sesión de carga para adjuntar un archivo a una todoTask. Especifique el archivo en el parámetro de entrada attachmentInfo.

Una operación correcta devuelve HTTP 201 Created y una nueva instancia uploadSession con una dirección URL opaca que se puede usar en operaciones de PUT posteriores para cargar partes del archivo. La instancia de uploadSession ofrece una ubicación de almacenamiento temporal en la que se guardan los bytes del archivo hasta que se cargue el archivo completo.

El objeto uploadSession en la respuesta también incluye la propiedad nextExpectedRanges, lo que indica que la primera ubicación de carga inicial debe ser el byte 0.

Permisos

Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.

Tipo de permiso	Permisos (de menos a más privilegiados)
Delegado (cuenta profesional o educativa)	Tasks.ReadWrite
Delegado (cuenta personal de Microsoft)	Tasks.ReadWrite
Aplicación	No admitida.

Ejemplo: crear una sesión de carga para una todoTask.

Solicitud

En el ejemplo siguiente se muestra una solicitud para crear una sesión de carga.

HTTP

POST https://graph.microsoft.com/beta/me/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachments/createUploadSession
Content-Type: application/json

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

C#

// Code snippets are only available for the latest version. Current version is 5.x

// Dependencies
using Microsoft.Graph.Beta.Me.Todo.Lists.Item.Tasks.Item.Attachments.CreateUploadSession;
using Microsoft.Graph.Beta.Models;

var requestBody = new CreateUploadSessionPostRequestBody
{
	AttachmentInfo = new AttachmentInfo
	{
		AttachmentType = AttachmentType.File,
		Name = "flower",
		Size = 3483322L,
	},
};

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.Me.Todo.Lists["{todoTaskList-id}"].Tasks["{todoTask-id}"].Attachments.CreateUploadSession.PostAsync(requestBody);

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

CLI

mgc-beta users todo lists tasks attachments create-upload-session post --user-id {user-id} --todo-task-list-id {todoTaskList-id} --todo-task-id {todoTask-id} --body '{\
  "attachmentInfo": {\
    "attachmentType": "file",\
    "name": "flower",\
    "size": 3483322\
  }\
}\
'

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Ir

// Code snippets are only available for the latest major version. Current major version is $v0.*

// Dependencies
import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-beta-sdk-go"
	  graphusers "github.com/microsoftgraph/msgraph-beta-sdk-go/users"
	  graphmodels "github.com/microsoftgraph/msgraph-beta-sdk-go/models"
	  //other-imports
)

requestBody := graphusers.NewItemCreateUploadSessionPostRequestBody()
attachmentInfo := graphmodels.NewAttachmentInfo()
attachmentType := graphmodels.FILE_ATTACHMENTTYPE 
attachmentInfo.SetAttachmentType(&attachmentType) 
name := "flower"
attachmentInfo.SetName(&name) 
size := int64(3483322)
attachmentInfo.SetSize(&size) 
requestBody.SetAttachmentInfo(attachmentInfo)

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=go
createUploadSession, err := graphClient.Me().Todo().Lists().ByTodoTaskListId("todoTaskList-id").Tasks().ByTodoTaskId("todoTask-id").Attachments().CreateUploadSession().Post(context.Background(), requestBody, nil)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Java

// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

com.microsoft.graph.beta.users.item.todo.lists.item.tasks.item.attachments.createuploadsession.CreateUploadSessionPostRequestBody createUploadSessionPostRequestBody = new com.microsoft.graph.beta.users.item.todo.lists.item.tasks.item.attachments.createuploadsession.CreateUploadSessionPostRequestBody();
AttachmentInfo attachmentInfo = new AttachmentInfo();
attachmentInfo.setAttachmentType(AttachmentType.File);
attachmentInfo.setName("flower");
attachmentInfo.setSize(3483322L);
createUploadSessionPostRequestBody.setAttachmentInfo(attachmentInfo);
var result = graphClient.me().todo().lists().byTodoTaskListId("{todoTaskList-id}").tasks().byTodoTaskId("{todoTask-id}").attachments().createUploadSession().post(createUploadSessionPostRequestBody);

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

JavaScript

const options = {
	authProvider,
};

const client = Client.init(options);

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

await client.api('/me/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachments/createUploadSession')
	.version('beta')
	.post(uploadSession);

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PHP

<?php
use Microsoft\Graph\Beta\GraphServiceClient;
use Microsoft\Graph\Beta\Generated\Users\Item\Todo\Lists\Item\Tasks\Item\Attachments\CreateUploadSession\CreateUploadSessionPostRequestBody;
use Microsoft\Graph\Beta\Generated\Models\AttachmentInfo;
use Microsoft\Graph\Beta\Generated\Models\AttachmentType;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestBody = new CreateUploadSessionPostRequestBody();
$attachmentInfo = new AttachmentInfo();
$attachmentInfo->setAttachmentType(new AttachmentType('file'));
$attachmentInfo->setName('flower');
$attachmentInfo->setSize(3483322);
$requestBody->setAttachmentInfo($attachmentInfo);

$result = $graphServiceClient->me()->todo()->lists()->byTodoTaskListId('todoTaskList-id')->tasks()->byTodoTaskId('todoTask-id')->attachments()->createUploadSession()->post($requestBody)->wait();

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

PowerShell

Import-Module Microsoft.Graph.Beta.Users

$params = @{
	attachmentInfo = @{
		attachmentType = "file"
		name = "flower"
		size = 3483322
	}
}

# A UPN can also be used as -UserId.
New-MgBetaUserTodoListTaskAttachmentUploadSession -UserId $userId -TodoTaskListId $todoTaskListId -TodoTaskId $todoTaskId -BodyParameter $params

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Python

# Code snippets are only available for the latest version. Current version is 1.x
from msgraph_beta import GraphServiceClient
from msgraph_beta.generated.users.item.todo.lists.item.tasks.item.attachments.create_upload_session.create_upload_session_post_request_body import CreateUploadSessionPostRequestBody
from msgraph_beta.generated.models.attachment_info import AttachmentInfo
from msgraph_beta.generated.models.attachment_type import AttachmentType
# To initialize your graph_client, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=python
request_body = CreateUploadSessionPostRequestBody(
	attachment_info = AttachmentInfo(
		attachment_type = AttachmentType.File,
		name = "flower",
		size = 3483322,
	),
)

result = await graph_client.me.todo.lists.by_todo_task_list_id('todoTaskList-id').tasks.by_todo_task_id('todoTask-id').attachments.create_upload_session.post(request_body)

Lea la documentación del SDK para obtener más información sobre cómo agregar el SDK al proyecto y crear una instancia de authProvider .

Respuesta

En el ejemplo siguiente se muestra el recurso uploadSession devuelto para la tarea en el cuerpo de la respuesta.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$metadata#microsoft.graph.uploadSession",
    "uploadUrl": "https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachmentSessions/AAMkADliMm=",
    "expirationDateTime": "2022-06-09T10:45:27.4324526Z",
    "nextExpectedRanges": [
        "0-"
    ]
}

Paso 2: usar la sesión de carga para cargar un rango de bytes del archivo

Para cargar el archivo o una parte del archivo, anexe /content a la dirección URL devuelta en el paso 1 de la propiedad uploadUrl del recurso uploadSession y realice una PUT solicitud en la dirección URL anexada. Puede cargar el archivo entero o dividirlo en varios trozos de bytes. Cada intervalo de bytes debe ser inferior a 4 MB.

Especifique los encabezados de solicitud y el cuerpo de la solicitud como se describe en las secciones siguientes.

Encabezados de solicitud

Nombre	Tipo	Descripción
Authorization	Cadena	{token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
Content-Length	Int32	El número de bytes que se están cargando en esta operación. Para mejorar el rendimiento, limite el número máximo de bytes para cada operación PUT a 4 MB. Se producirá un error en la solicitud para cualquier valor superior a 4 MB. Obligatorio.
Content-Range	Cadena	El rango de bytes basado en 0 del archivo que se carga en esta operación, expresado en formato bytes {start}-{end}/{total}. Obligatorio.
Content-Type	Cadena	El tipo MIME. Especifique application/octet-stream. Obligatorio.

Cuerpo de la solicitud

Especifique los bytes reales del archivo que se va a adjuntar y que se encuentran en el rango de la ubicación especificado en el encabezado de solicitud Content-Range.

Respuesta

Una carga correcta devuelve un código de respuesta HTTP 200 OK y un objeto uploadSession. Tenga en cuenta lo siguiente en el objeto de respuesta:

• El valor de la propiedad expirationDateTime sigue siendo el mismo que devolvió uploadSession inicialmente en el paso 1.
• El nextExpectedRanges especifica la siguiente ubicación de bytes desde la que se va a empezar a cargar, por ejemplo, "nextExpectedRanges":["2097152"]. Debe cargar los bytes de un archivo en orden.

• La propiedad uploadUrl no se devuelve explícitamente, ya que todas las operaciones de PUT de una sesión de carga usan la misma dirección URL devuelta al crear la sesión (paso 1).

Ejemplo: cargar primero en la todoTask

Solicitud

En el ejemplo siguiente se muestra la solicitud.

PUT https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachmentSessions/AAMkADliMm=/content
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>
}

Respuesta

A continuación puede ver un ejemplo de la respuesta que muestra el inicio del siguiente intervalo de bytes que espera el servidor en la propiedad nextExpectedRanges.

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

{
  "ExpirationDateTime":"2022-06-09T10:45:27.4324526Z",
  "NextExpectedRanges":["2097152"]
}

Paso 3: seguir cargando intervalos de bytes hasta que se haya cargado todo el archivo

Después de la carga inicial en el paso 2, siga cargando la parte restante del archivo con una solicitud de PUT similar, como se describe en el paso 2, antes de que llegue a la fecha y hora de expiración de la sesión. Use la colección nextExpectedRanges para determinar dónde iniciar el siguiente intervalo de bytes que se va a cargar. Es posible que vea varios intervalos especificados, lo que indica las partes del archivo que aún no ha recibido el servidor. Esto resulta útil si necesita reanudar una transferencia que se ha interrumpido y su cliente no está seguro del estado del servicio.

Una vez que el último byte del archivo se ha cargado correctamente, la operación final de PUT devuelve un código de respuesta HTTP 201 Created y un encabezado Location que indica la dirección URL de los datos adjuntos del archivo. Puede obtener el ID. de datos adjuntos desde la URL y guardarlo para usarlo más adelante.

En los ejemplos siguientes se muestra cómo cargar el último intervalo de bytes del archivo en todoTask en los pasos anteriores.

Ejemplo: carga final en todoTask

Solicitud

En el ejemplo siguiente se muestra la solicitud.

PUT https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachmentSessions/AAMkADliMm=/content
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>
}

Respuesta

El siguiente es un ejemplo de la respuesta que muestra un encabezado de respuesta Location desde el que puede guardar el identificador de datos adjuntos (AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=) para su uso posterior.

HTTP/1.1 201 Created

Location: https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/Attachments/AAMkADI5MAAIT3drCAAABEgAQANAqbAe7qaROhYdTnUQwXm0=
Content-Length: 0

Paso alternativo: cancelar la sesión de carga

Si tiene que cancelar la carga en cualquier momento antes de que la sesión expire, puede usar la misma URL inicial para eliminar la sesión de carga. Una operación correcta devuelve un código de respuesta HTTP 204 No Content.

Ejemplo: Cancelar la sesión de carga

Solicitud

En el ejemplo siguiente se muestra la solicitud.

DELETE https://graph.microsoft.com/beta/users/6f9a2a92-8527-4d64-837e-b5312852f36d/todo/lists/AAMDiFkfh=/tasks/AAMkADliMm=/attachmentSessions/AAMkADliMm=

Respuesta

En el ejemplo siguiente se muestra la respuesta.

HTTP/1.1 204 No content