ファイルを送受信する

ListAsync() を使用して、現在のメッセージに添付されているサポートされているすべてのファイルにアクセスします。

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 と値:

• context.Files.ListAsync: ファイル バイトをダウンロードせずにファイル メタデータを返します。
• file.Name: アップローダーが指定した名前を読み取る場合は表示のみです。

ListAsync() 添付ファイルの順序を保持します。 サポートされているファイルのないアクティビティの空のコレクションを返し、不正な形式のファイル エントリをスキップします。 ハンドラーが 1 つのファイルを想定している場合は、 FirstAsync() を使用します。

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

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

主要な API と値:

• FirstAsync: サポートされている最初のファイルまたは nullを返します。
• file.Name: 受信したファイルのアップローダーが指定した名前を表示します。

list() を使用して、現在のメッセージに添付されているサポートされているすべてのファイルにアクセスします。

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 と値:

• files.list: ファイル バイトをダウンロードせずにファイル メタデータを返します。
• file.name: アップローダーが指定した名前を読み取る場合は表示のみです。

list() 添付ファイルの順序を保持します。 サポートされているファイルのないアクティビティの場合は空の配列を返し、不正な形式のファイル エントリをスキップします。 ハンドラーが 1 つのファイルを想定している場合は、 first() を使用します。

const file = await files.first();

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

主要な API と値:

• first: サポートされている最初のファイルまたは undefinedを返します。
• file.name: 受信したファイルのアップローダーが指定した名前を表示します。

list() を使用して、現在のメッセージに添付されているサポートされているすべてのファイルにアクセスします。

@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 と値:

• ctx.files.list: ファイル バイトをダウンロードせずにファイル メタデータを返します。
• file.name: アップローダーが指定した名前を読み取る場合は表示のみです。

list() 添付ファイルの順序を保持します。 サポートされているファイルのないアクティビティの空のリストを返し、不正な形式のファイル エントリをスキップします。 ハンドラーが 1 つのファイルを想定している場合は、 first() を使用します。

file = await ctx.files.first()

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

主要な API と値:

• first: サポートされている最初のファイルまたは Noneを返します。
• file.name: 受信したファイルのアップローダーが指定した名前を表示します。

DownloadAsync() を使用して、再利用可能なメモリ内コピーにファイルをダウンロードします。

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 と値:

• DownloadAsync: 再利用可能なバイト コピー 1 つを取得してバッファーに格納します。
• downloaded.Bytes: ダウンロードしたファイルの完全なバイナリ コンテンツにアクセスします。
• downloaded.ContentType: 解決済みの MIME の種類を処理に使用します。
• downloaded.Filename: 解決された名前を表示目的で使用します。

その他の読み取りオプションは次のとおりです。

• TextAsync(): 既定では、テキストを UTF-8 としてダウンロードおよびデコードします。
• StreamAsync(): 大きなファイルを完全にバッファリングせずに処理します。
• SaveAsAsync(path): バイトを安全なローカル パスに直接Streamします。

TextAsync() 無効なバイト シーケンスを U+FFFD に置き換えます。 UTF-8 以外のテキスト用に Encoding を提供し、バイナリ ファイルをバイトまたはストリームとして処理します。

IncomingFileはバイトをキャッシュしません。 DownloadAsync()、TextAsync()、StreamAsync()、または SaveAsAsync() を呼び出すたびに、別のネットワーク要求が実行されます。 同じコンテンツを 1 回ダウンロードして、 DownloadedFile を複数回必要になったときに再利用してください。

DownloadedFile downloaded =
    await file.DownloadAsync(cancellationToken);

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

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

主要な API と値:

• downloaded.Text(): バッファーされたコピーを、別のダウンロードを必要とせずにデコードします。
• downloaded.Bytes: バッファーされたバイトをバイナリ処理に再利用します。
• SaveAsAsync: ファイルを再度フェッチせずに、バッファーされたバイトを保存します。

download() を使用して、再利用可能なメモリ内コピーにファイルをダウンロードします。

const file = await files.first();

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

主要な API と値:

• download: 再利用可能なバイト コピー 1 つを取得してバッファーに格納します。
• downloaded.bytes: ダウンロードしたファイルのバイナリ コンテンツにアクセスします。
• downloaded.contentType: 解決済みの MIME の種類を処理に使用します。
• downloaded.filename: 解決された名前を表示目的で使用します。

その他の読み取りオプションは次のとおりです。

• text(): 既定では、テキストを UTF-8 としてダウンロードおよびデコードします。
• stream(): 大きなファイルを完全にバッファリングせずに処理します。
• saveAs(path): バイトを安全なローカル パスに直接Streamします。

受信ファイルはバイトをキャッシュしません。 同じコンテンツを 1 回ダウンロードして、ダウンロードしたファイルを複数回必要になったときに再利用します。

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

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

主要な API と値:

• downloaded.text(): バッファーされたコピーを、別のダウンロードを必要とせずにデコードします。
• downloaded.arrayBuffer(): バッファーされたバイトをバイナリ処理に再利用します。
• saveAs: ファイルを再度フェッチせずに、バッファーされたバイトを保存します。

download() を使用して、再利用可能なメモリ内コピーにファイルをダウンロードします。

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 と値:

• download: 再利用可能なバイト コピー 1 つを取得してバッファーに格納します。
• downloaded.bytes: ダウンロードしたファイルのバイナリ コンテンツにアクセスします。
• downloaded.content_type: 解決済みの MIME の種類を処理に使用します。
• downloaded.filename: 解決された名前を表示目的で使用します。

その他の読み取りオプションは次のとおりです。

• text(): 既定では、テキストを UTF-8 としてダウンロードおよびデコードします。
• stream(): 大きなファイルを完全にバッファリングせずに処理します。
• save_as(path): バイトを安全なローカル パスに直接Streamします。

受信ファイルはバイトをキャッシュしません。 同じコンテンツを 1 回ダウンロードして、ダウンロードしたファイルを複数回必要になったときに再利用します。

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

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

主要な API と値:

• downloaded.text(): バッファーされたコピーを、別のダウンロードを必要とせずにデコードします。
• downloaded.bytes: バッファーされたバイトをバイナリ処理に再利用します。
• save_as: ファイルを再度フェッチせずに、バッファーされたバイトを保存します。

IncomingFile.Raw は、元のプロトコル ペイロードが必要な場合にのみ使用してください。 次の例では、オブジェクト全体をシリアル化するのではなく、添付ファイル名とコンテンツ タイプをログに記録します。

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 と値:

• file.Raw: 診断またはトラブルシューティングのために元のメタデータにアクセスします。
• file.Raw.Name: 秘密度を検証した後にのみ、表示名をログに記録します。
• file.Raw.ContentType: URL を公開せずに、添付ファイルの種類をログに記録します。
• logger.LogDebug: 完全なペイロードではなく、選択したメタデータを記録します。

IIncomingFile.raw は、元のプロトコル ペイロードが必要な場合にのみ使用してください。 次の例では、完全なオブジェクトではなく、添付ファイル名とコンテンツ タイプをログに記録します。

const file = await files.first();

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

主要な API と値:

• file.raw: 診断またはトラブルシューティングのために元のメタデータにアクセスします。
• file.raw.name: 秘密度を検証した後にのみ、表示名をログに記録します。
• file.raw.contentType: URL を公開せずに、添付ファイルの種類をログに記録します。
• log.debug: 完全なペイロードではなく、選択したメタデータを記録します。

IncomingFile.raw は、元のプロトコル ペイロードが必要な場合にのみ使用してください。 次の例では、完全なオブジェクトではなく、添付ファイル名とコンテンツ タイプをログに記録します。

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 と値:

• file.raw: 診断またはトラブルシューティングのために元のメタデータにアクセスします。
• file.raw.name: 秘密度を検証した後にのみ、表示名をログに記録します。
• file.raw.content_type: URL を公開せずに、添付ファイルの種類をログに記録します。
• ctx.logger.debug: 完全なペイロードではなく、選択したメタデータを記録します。

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}.");
    }
}

キー パラメーターと値:

• url: 承諾後に返される UploadInfo.UploadUrl を使用します。
• content: 同意に関連付けられている正確なバイト数を指定します。
• content.Length: バイト範囲を作成する前に空のアップロードを拒否します。
• ContentType: バイナリ転送の application/octet-stream を設定します。
• ContentLength: アップロードされるバイト数の正確な数を設定します。
• ContentRange: アップロードされたバイト範囲と合計を指定します。
• httpClient.SendAsync: HTTP PUT 要求を OneDrive に送信します。
• response.StatusCode: HTTP 200 または 201 を受け入れ、それ以外の場合は失敗します。

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}`);
  }
}

キー パラメーターと値:

• url: 承諾後に返される uploadInfo.uploadUrl を使用します。
• content: 同意に関連付けられている正確なバイト数を指定します。
• content.length: バイト範囲を作成する前に空のアップロードを拒否します。
• Content-Type: バイナリ ファイル転送の application/octet-stream を設定します。
• Content-Length: アップロードされるバイトの 10 進数の長さを設定します。
• Content-Range: アップロードされたバイト範囲と合計を指定します。
• axios.put: HTTP PUT 要求を使用してバイトをアップロードします。
• response.status: HTTP 200 または 201 を受け入れ、他の応答で失敗します。

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

キー パラメーターと値:

• url: 承諾後に返される upload_info.upload_url を使用します。
• content: 同意に関連付けられている正確なバイト数を指定します。
• if not content: バイト範囲を作成する前に空のアップロードを拒否します。
• Content-Type: バイナリ転送の application/octet-stream を設定します。
• Content-Length: アップロードされるバイト数の正確な数を設定します。
• Content-Range: アップロードされたバイト範囲と合計を指定します。
• httpx.AsyncClient.put: HTTP PUT 要求を使用してバイトをアップロードします。
• response.status_code: HTTP 200 または 201 を受け入れ、それ以外の場合は失敗します。

403 は、同意が見つからない、項目アクセスが見つからない、または存在しない項目を表す場合があります。 SDK では、これらの応答に対して個別の "ファイルが見つかりません" エラーは公開されません。

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);
}

キーの型と値:

• FileCredentialException: 不足しているエージェント ユーザーの Graph 資格情報構成を処理します。
• FileAccessException.Status: 拒否されたトークンと拒否されたアクセスを区別します。
• FileUrlExpiredException: 期限切れのボット ダウンロード URL を処理します。
• FileScopeNotSupportedException: サポートされていないグループまたはチャネルの取得を処理します。
• FileException: 既知の 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;
  }
}

キーの型と値:

• FileCredentialError: 不足している agentic-user Graph 資格情報を処理します。
• FileAccessError.status: 拒否されたトークンと拒否されたアクセスを区別します。
• FileUrlExpiredError: 期限切れのボット ダウンロード URL を処理します。
• FileScopeNotSupportedError: サポートされていない会話スコープを処理します。
• FileError: 既知の 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.")

キーの型と値:

• FileCredentialError: 不足している agentic-user Graph 資格情報を処理します。
• FileAccessError.status: 拒否されたトークンと拒否されたアクセスを区別します。
• FileUrlExpiredError: 期限切れのボット ダウンロード URL を処理します。
• FileScopeNotSupportedError: サポートされていない会話スコープを処理します。
• FileError: 既知の SDK エラーのフォールバック処理を提供します。