Envío y recepción de archivos

Se usa ListAsync() para tener acceso a todos los archivos compatibles adjuntos al mensaje actual:

teamsApp.OnMessage(async (context, cancellationToken) =>
{
    IList<IncomingFile> files =
        await context.Files.ListAsync(cancellationToken);

    if (files.Count == 0)
    {
        await context.ReplyAsync(
            "Attach a file and I will read it.",
            cancellationToken);
        return;
    }

    string names = string.Join(", ", files.Select(file => file.Name));
    await context.ReplyAsync(
        $"You sent {files.Count} file(s): {names}",
        cancellationToken);
});

API y valores clave:

• context.Files.ListAsync: devuelve metadatos de archivo sin descargar bytes de archivo.
• file.Name: lee el nombre proporcionado por el cargador para solo mostrar.

ListAsync() Conserva el orden de los datos adjuntos. Devuelve una colección vacía para las actividades sin archivos compatibles y omite las entradas de archivo con formato incorrecto. Úselo FirstAsync() cuando su controlador espera un archivo:

IncomingFile? file =
    await context.Files.FirstAsync(cancellationToken);

if (file is not null)
{
    await context.ReplyAsync(
        $"Reading {file.Name}...",
        cancellationToken);
}

API y valores clave:

• FirstAsync: devuelve el primer archivo admitido o null.
• file.Name: muestra el nombre proporcionado por el cargador del archivo recibido.

Se usa list() para tener acceso a todos los archivos compatibles adjuntos al mensaje actual:

app.on('message', async ({ files, send }) => {
  const attached = await files.list();

  if (attached.length === 0) {
    await send('Attach a file and I will read it.');
    return;
  }

  const names = attached.map((file) => file.name).join(', ');
  await send(`You sent ${attached.length} file(s): ${names}`);
});

API y valores clave:

• files.list: devuelve metadatos de archivo sin descargar bytes de archivo.
• file.name: lee el nombre proporcionado por el cargador para solo mostrar.

list() Conserva el orden de los datos adjuntos. Devuelve una matriz vacía para las actividades sin archivos compatibles y omite las entradas de archivo con formato incorrecto. Úselo first() cuando su controlador espera un archivo:

const file = await files.first();

if (file) {
  await send(`Reading ${file.name}...`);
}

API y valores clave:

• first: devuelve el primer archivo admitido o undefined.
• file.name: muestra el nombre proporcionado por el cargador del archivo recibido.

Se usa list() para tener acceso a todos los archivos compatibles adjuntos al mensaje actual:

@app.on_message
async def handle_message(ctx: ActivityContext[MessageActivity]) -> None:
    attached = await ctx.files.list()

    if not attached:
        await ctx.reply("Attach a file and I will read it.")
        return

    names = ", ".join(file.name for file in attached)
    await ctx.reply(f"You sent {len(attached)} file(s): {names}")

API y valores clave:

• ctx.files.list: devuelve metadatos de archivo sin descargar bytes de archivo.
• file.name: lee el nombre proporcionado por el cargador para solo mostrar.

list() Conserva el orden de los datos adjuntos. Devuelve una lista vacía para las actividades sin archivos compatibles y omite las entradas de archivo con formato incorrecto. Úselo first() cuando su controlador espera un archivo:

file = await ctx.files.first()

if file:
    await ctx.reply(f"Reading {file.name}...")

API y valores clave:

• first: devuelve el primer archivo admitido o None.
• file.name: muestra el nombre proporcionado por el cargador del archivo recibido.

Se usa DownloadAsync() para descargar un archivo en una copia reutilizable en memoria:

IncomingFile? file =
    await context.Files.FirstAsync(cancellationToken);

if (file is not null)
{
    DownloadedFile downloaded =
        await file.DownloadAsync(cancellationToken);

    await context.ReplyAsync(
        $"Downloaded {downloaded.Filename} " +
        $"({downloaded.Bytes.Length} bytes, {downloaded.ContentType}).",
        cancellationToken);
}

API y valores clave:

• DownloadAsync: Capturar y almacenar en búfer una copia reutilizable de bytes.
• downloaded.Bytes: acceda al contenido binario completo del archivo descargado.
• downloaded.ContentType: use el tipo MIME resuelto para el procesamiento.
• downloaded.Filename: usa el nombre resuelto para mostrar el nombre.

Otras opciones de lectura incluyen:

• TextAsync(): descarga y descodifica texto como UTF-8 de forma predeterminada.
• StreamAsync(): procese archivos grandes sin almacenarlos en búfer por completo.
• SaveAsAsync(path): haga Stream bytes directamente a una ruta de acceso local segura.

TextAsync() Reemplaza las secuencias de bytes no válidas por U+FFFD. Proporcione un Encoding texto no UTF-8 y procese archivos binarios como bytes o secuencias.

An IncomingFile no almacena bytes en memoria caché. Cada llamada a DownloadAsync(), TextAsync(), StreamAsync(), o SaveAsAsync() realiza otra solicitud de red. Descárgalo una vez y vuelve a usarlo DownloadedFile cuando necesites el mismo contenido más de una vez:

DownloadedFile downloaded =
    await file.DownloadAsync(cancellationToken);

string text = downloaded.Text();
byte[] bytes = downloaded.Bytes;

await downloaded.SaveAsAsync(
    "./downloads/copy.bin",
    cancellationToken);

API y valores clave:

• downloaded.Text(): descodifica la copia almacenada en búfer sin otra descarga.
• downloaded.Bytes: reutilizar los bytes almacenados en búfer para el procesamiento binario.
• SaveAsAsync: guarde los bytes almacenados en búfer sin recuperar el archivo de nuevo.

Se usa download() para descargar un archivo en una copia reutilizable en memoria:

const file = await files.first();

if (file) {
  const downloaded = await file.download();
  await send(
    `Downloaded ${downloaded.filename} ` +
    `(${downloaded.bytes.length} bytes, ${downloaded.contentType}).`
  );
}

API y valores clave:

• download: Capturar y almacenar en búfer una copia reutilizable de bytes.
• downloaded.bytes: acceda al contenido binario del archivo descargado.
• downloaded.contentType: use el tipo MIME resuelto para el procesamiento.
• downloaded.filename: usa el nombre resuelto para mostrar el nombre.

Otras opciones de lectura incluyen:

• text(): descarga y descodifica texto como UTF-8 de forma predeterminada.
• stream(): procese archivos grandes sin almacenarlos en búfer por completo.
• saveAs(path): haga Stream bytes directamente a una ruta de acceso local segura.

Un archivo entrante no almacena bytes en la memoria caché. Descarga una vez y vuelve a usar el archivo descargado cuando necesites el mismo contenido más de una vez:

const downloaded = await file.download();
const text = downloaded.text();
const buffer = downloaded.arrayBuffer();

await downloaded.saveAs('./downloads/copy.bin');

API y valores clave:

• downloaded.text(): descodifica la copia almacenada en búfer sin otra descarga.
• downloaded.arrayBuffer(): reutilizar los bytes almacenados en búfer para el procesamiento binario.
• saveAs: guarde los bytes almacenados en búfer sin recuperar el archivo de nuevo.

Se usa download() para descargar un archivo en una copia reutilizable en memoria:

file = await ctx.files.first()

if file:
    downloaded = await file.download()
    await ctx.reply(
        f"Downloaded {downloaded.filename} "
        f"({len(downloaded.bytes)} bytes, {downloaded.content_type})."
    )

API y valores clave:

• download: Capturar y almacenar en búfer una copia reutilizable de bytes.
• downloaded.bytes: acceda al contenido binario del archivo descargado.
• downloaded.content_type: use el tipo MIME resuelto para el procesamiento.
• downloaded.filename: usa el nombre resuelto para mostrar el nombre.

Otras opciones de lectura incluyen:

• text(): descarga y descodifica texto como UTF-8 de forma predeterminada.
• stream(): procese archivos grandes sin almacenarlos en búfer por completo.
• save_as(path): haga Stream bytes directamente a una ruta de acceso local segura.

Un archivo entrante no almacena bytes en la memoria caché. Descarga una vez y vuelve a usar el archivo descargado cuando necesites el mismo contenido más de una vez:

downloaded = await file.download()
text = downloaded.text()
data = downloaded.bytes

await downloaded.save_as("./downloads/copy.bin")

API y valores clave:

• downloaded.text(): descodifica la copia almacenada en búfer sin otra descarga.
• downloaded.bytes: reutilizar los bytes almacenados en búfer para el procesamiento binario.
• save_as: guarde los bytes almacenados en búfer sin recuperar el archivo de nuevo.

Úselo IncomingFile.Raw solo cuando necesite la carga útil del protocolo original. En el ejemplo siguiente se registran el nombre de los datos adjuntos y el tipo de contenido, en lugar de serializar el objeto completo:

IncomingFile? file =
    await context.Files.FirstAsync(cancellationToken);

if (file is not null)
{
    logger.LogDebug(
        "File attachment received. Name: {Name}; Content type: {ContentType}",
        file.Raw.Name,
        file.Raw.ContentType);
}

API y valores clave:

• file.Raw: accede a los metadatos originales para diagnóstico o solución de problemas.
• file.Raw.Name: registre el nombre para mostrar sólo después de validar su confidencialidad.
• file.Raw.ContentType: registra el tipo de datos adjuntos sin exponer sus direcciones URL.
• logger.LogDebug: registra los metadatos seleccionados en lugar de la carga completa.

Úselo IIncomingFile.raw solo cuando necesite la carga útil del protocolo original. En el ejemplo siguiente se registran el nombre de los datos adjuntos y el tipo de contenido, en lugar del objeto completo:

const file = await files.first();

if (file) {
  log.debug('File attachment received', {
    name: file.raw.name,
    contentType: file.raw.contentType
  });
}

API y valores clave:

• file.raw: accede a los metadatos originales para diagnóstico o solución de problemas.
• file.raw.name: registre el nombre para mostrar sólo después de validar su confidencialidad.
• file.raw.contentType: registra el tipo de datos adjuntos sin exponer sus direcciones URL.
• log.debug: registra los metadatos seleccionados en lugar de la carga completa.

Úselo IncomingFile.raw solo cuando necesite la carga útil del protocolo original. En el ejemplo siguiente se registran el nombre de los datos adjuntos y el tipo de contenido, en lugar del objeto completo:

file = await ctx.files.first()

if file:
    ctx.logger.debug(
        "File attachment received. Name: %s; Content type: %s",
        file.raw.name,
        file.raw.content_type,
    )

API y valores clave:

• file.raw: accede a los metadatos originales para diagnóstico o solución de problemas.
• file.raw.name: registre el nombre para mostrar sólo después de validar su confidencialidad.
• file.raw.content_type: registra el tipo de datos adjuntos sin exponer sus direcciones URL.
• ctx.logger.debug: registra los metadatos seleccionados en lugar de la carga completa.

using System.Net;
using System.Net.Http.Headers;

async Task UploadToOneDrive(
    string url,
    byte[] content,
    CancellationToken cancellationToken)
{
    if (content.Length == 0)
    {
        throw new ArgumentException(
            "The file content must not be empty.",
            nameof(content));
    }

    using var request = new HttpRequestMessage(HttpMethod.Put, url);
    request.Content = new ByteArrayContent(content);
    request.Content.Headers.ContentType =
        new MediaTypeHeaderValue("application/octet-stream");
    request.Content.Headers.ContentLength = content.Length;
    request.Content.Headers.ContentRange =
        new ContentRangeHeaderValue(0, content.Length - 1, content.Length);

    using HttpResponseMessage response =
        await httpClient.SendAsync(request, cancellationToken);

    if (response.StatusCode is not HttpStatusCode.OK
        and not HttpStatusCode.Created)
    {
        throw new HttpRequestException(
            $"Upload failed with status {response.StatusCode}.");
    }
}

Parámetros y valores clave:

• url: usar el devuelto después de la UploadInfo.UploadUrl aceptación.
• content: proporciona los bytes exactos asociados al consentimiento.
• content.Length: rechaza una carga vacía antes de crear su intervalo de bytes.
• ContentType: Configurado application/octet-stream para la transferencia binaria.
• ContentLength: establece el número exacto de bytes cargados.
• ContentRange: describe el intervalo de bytes cargado y el total.
• httpClient.SendAsync: envía la solicitud HTTP PUT a OneDrive.
• response.StatusCode: acepta HTTP 200 o 201 y en caso contrario, fracasar.

import axios from 'axios';

async function uploadToOneDrive(url: string, content: Buffer): Promise<void> {
  if (content.length === 0) {
    throw new Error('The file content must not be empty.');
  }

  const fileSize = content.length;
  const response = await axios.put(url, content, {
    headers: {
      'Content-Type': 'application/octet-stream',
      'Content-Length': fileSize.toString(),
      'Content-Range': `bytes 0-${fileSize - 1}/${fileSize}`
    }
  });

  if (![200, 201].includes(response.status)) {
    throw new Error(`Upload failed with status ${response.status}`);
  }
}

Parámetros y valores clave:

• url: usar el devuelto después de la uploadInfo.uploadUrl aceptación.
• content: proporciona los bytes exactos asociados al consentimiento.
• content.length: rechaza una carga vacía antes de crear su intervalo de bytes.
• Content-Type: Configurado application/octet-stream para la transferencia de archivos binarios.
• Content-Length: establece la longitud decimal de los bytes cargados.
• Content-Range: describe el intervalo de bytes cargado y el total.
• axios.put: cargue los bytes con una solicitud HTTP PUT .
• response.status: acepta HTTP 200 o 201 y falla en otras respuestas.

import httpx

async def upload_to_onedrive(url: str, content: bytes) -> None:
    if not content:
        raise ValueError("The file content must not be empty.")

    file_size = len(content)
    headers = {
        "Content-Type": "application/octet-stream",
        "Content-Length": str(file_size),
        "Content-Range": f"bytes 0-{file_size - 1}/{file_size}",
    }

    async with httpx.AsyncClient() as client:
        response = await client.put(url, content=content, headers=headers)

    if response.status_code not in (200, 201):
        raise RuntimeError(
            f"Upload failed with status {response.status_code}"
        )

Parámetros y valores clave:

• url: usar el devuelto después de la upload_info.upload_url aceptación.
• content: proporciona los bytes exactos asociados al consentimiento.
• if not content: rechaza una carga vacía antes de crear su intervalo de bytes.
• Content-Type: Configurado application/octet-stream para la transferencia binaria.
• Content-Length: establece el número exacto de bytes cargados.
• Content-Range: describe el intervalo de bytes cargado y el total.
• httpx.AsyncClient.put: cargue los bytes con una solicitud HTTP PUT .
• response.status_code: acepta HTTP 200 o 201 y en caso contrario, fracasar.

Una puede representar consentimiento que falta, acceso a 403 elemento que falta o un elemento inexistente. El SDK no expone un error de archivo no encontrado independiente para estas respuestas.

try
{
    DownloadedFile downloaded =
        await file.DownloadAsync(cancellationToken);
}
catch (FileCredentialException)
{
    await context.ReplyAsync(
        "The agent isn't configured to access this file.",
        cancellationToken);
}
catch (FileAccessException error)
{
    await context.ReplyAsync(
        $"The storage service denied access ({error.Status}).",
        cancellationToken);
}
catch (FileUrlExpiredException)
{
    await context.ReplyAsync(
        "That file link expired. Attach the file again.",
        cancellationToken);
}
catch (FileScopeNotSupportedException)
{
    await context.ReplyAsync(
        "File download isn't supported in this conversation.",
        cancellationToken);
}
catch (FileException)
{
    await context.ReplyAsync(
        "The file couldn't be read.",
        cancellationToken);
}

Tipos y valores de clave:

• FileCredentialException: Gestionar la configuración de las credenciales de Graph del usuario agente que falta.
• FileAccessException.Status: distingue los tokens rechazados del acceso denegado.
• FileUrlExpiredException: Gestionar las direcciones URL de descarga del bot expiradas.
• FileScopeNotSupportedException: Controlar la recuperación de grupos o canales no admitidos.
• FileException: proporciona control de reserva para errores conocidos del SDK.

try {
  const downloaded = await file.download();
} catch (error) {
  if (error instanceof FileCredentialError) {
    await send("The agent isn't configured to access this file.");
  } else if (error instanceof FileAccessError) {
    await send(`The storage service denied access (${error.status}).`);
  } else if (error instanceof FileUrlExpiredError) {
    await send('That file link expired. Attach the file again.');
  } else if (error instanceof FileScopeNotSupportedError) {
    await send("File download isn't supported in this conversation.");
  } else if (error instanceof FileError) {
    await send("The file couldn't be read.");
  } else {
    throw error;
  }
}

Tipos y valores de clave:

• FileCredentialError: Gestionar las credenciales de Graph del usuario agente que faltan.
• FileAccessError.status: distingue los tokens rechazados del acceso denegado.
• FileUrlExpiredError: Gestionar las direcciones URL de descarga del bot expiradas.
• FileScopeNotSupportedError: controlar ámbitos de conversación no admitidos.
• FileError: proporciona control de reserva para errores conocidos del SDK.

try:
    downloaded = await file.download()
except FileCredentialError:
    await ctx.reply("The agent isn't configured to access this file.")
except FileAccessError as error:
    await ctx.reply(
        f"The storage service denied access ({error.status})."
    )
except FileUrlExpiredError:
    await ctx.reply("That file link expired. Attach the file again.")
except FileScopeNotSupportedError:
    await ctx.reply(
        "File download isn't supported in this conversation."
    )
except FileError:
    await ctx.reply("The file couldn't be read.")

Tipos y valores de clave:

• FileCredentialError: Gestionar las credenciales de Graph del usuario agente que faltan.
• FileAccessError.status: distingue los tokens rechazados del acceso denegado.
• FileUrlExpiredError: Gestionar las direcciones URL de descarga del bot expiradas.
• FileScopeNotSupportedError: controlar ámbitos de conversación no admitidos.
• FileError: proporciona control de reserva para errores conocidos del SDK.