ファイルを送受信する

重要

  • エージェントは、Government Community Cloud High (GCC High)、国防総省 (DoD)、および 21Vianet 環境が運用する Teams でのファイルの送受信はサポートしていません。

ファイルの送受信には 2 つの方法があります。

Graph API を使用する

OneDrive および SharePoint 用の Graph API を使用して、既存の SharePoint ファイルを参照するカードが添付されたメッセージを投稿します。 Graph API を使用するには、標準の OAuth 2.0 承認フローを使用して、次のいずれかにアクセスします。

  • ユーザーの OneDrive フォルダー personal および groupchat ファイル。
  • チームのチャネル内のファイルの channel ファイル。

Graph API は、すべての Teams スコープで機能します。 詳細については、「チャット メッセージ ファイルの添付ファイルの送信」を参照してください。

または、Teams SDK ファイル同意 API を使用してエージェントとファイルを送受信できます。

Teams SDK ファイル同意 API は、 personal コンテキストでのみ機能します。 channelまたはgroupchatのコンテキストでは機能しません。

Teams SDK を使用すると、エージェントは personal コンテキスト (個人用チャットとも呼ばれる) でユーザーとファイルを直接送受信できます。 経費レポート、画像認識、ファイル アーカイブ、ファイル コンテンツの編集に関連する電子署名などの機能を実装します。 Teams で共有されるファイルは通常、カードとして表示され、アプリ内で豊富に表示できます。

次のセクションでは、メッセージの送信など、ユーザーとの直接的なやり取りとしてファイル コンテンツを送信する方法について説明します。 Teams SDK には、 file.consent.accept や file.consent.declineなど、ファイルの同意ワークフローを処理するためのアクティビティ ルートが用意されています。

ファイルをサポートするようにエージェントを構成する

エージェントでファイルを送受信するには、マニフェストの supportsFiles プロパティを true に設定します。 このプロパティについては、マニフェスト リファレンスの ボット セクションで説明されています。

NDR は、次のようになっています: "supportsFiles": true。 エージェントが supportsFilesを有効にしない場合、このセクションに記載されている機能は機能しません。

個人用チャットでファイルを受信する

ユーザーがエージェントにファイルを送信すると、ファイルはまずユーザーの OneDrive for Business ストレージにアップロードされます。 その後、エージェントは、ユーザー アップロードについてユーザーに通知するメッセージ アクティビティを受信します。 アクティビティには、名前やコンテンツ URL などのファイル メタデータが含まれます。 ユーザーは、この URL から直接読み取って、バイナリ コンテンツを取得できます。

ファイル添付の例を使用したメッセージ アクティビティ

次のコードは、添付ファイルを含むメッセージ アクティビティの例を示しています。

{
  "attachments": [{
    "contentType": "application/vnd.microsoft.teams.file.download.info",
    "contentUrl": "https://contoso.sharepoint.com/personal/johnadams_contoso_com/Documents/Applications/file_example.txt",
    "name": "file_example.txt",
    "content": {
      "downloadUrl" : "https://download.link",
      "uniqueId": "1150D938-8870-4044-9F2C-5BBDEBA70C9D",
      "fileType": "txt",
      "etag": "123"
    }
  }]
}

次の表で、添付ファイルのコンテンツ プロパティについて説明します。

プロパティ 用途
downloadUrl ファイルのコンテンツを取得するための OneDrive URL。 この URL から直接 HTTP GET を発行できます。
uniqueId 一意のファイル ID。 ユーザーがエージェントにファイルを送信する場合の、これは OneDrive ドライブのアイテム ID です。
fileType .pdf や .docx などのファイルの種類。

ベスト プラクティスとして、ユーザーにメッセージを送信してファイルのアップロードを確認します。

個人用チャットへのファイルのアップロード

ユーザーにファイルをアップロードするには:

  1. ファイルの書き込み許可を要求するメッセージをユーザーに送信します。 このメッセージには、アップロードするファイルの名前が記載された FileConsentCard 個の添付ファイルが含まれている必要があります。
  2. ユーザーがファイルのダウンロードを受け入れると、エージェントは場所 URL を含む呼び出しアクティビティを受信します。
  3. ファイルを転送するために、エージェントは指定された場所 URL に直接 HTTP POST を実行します。
  4. ユーザーが同じファイルのそれ以上のアップロードを受け入れないようにする場合は、必要に応じて、元の同意カードを削除します。

アップロードの許可を求めるメッセージ

次のデスクトップ メッセージには、ファイルをアップロードするためのユーザー権限を要求する単純な添付オブジェクトが含まれています。

ファイルのアップロードに対するユーザー権限を要求する同意カード

次のモバイル メッセージには、ファイルをアップロードするためのユーザー権限を要求する添付オブジェクトが含まれています。

モバイルにファイルをアップロードするためのユーザーのアクセス許可を要求する同意カード
{
  "attachments": [{
    "contentType": "application/vnd.microsoft.teams.card.file.consent",
    "name": "file_example.txt",
    "content": {
      "description": "<Purpose of the file, such as: this is your monthly expense report>",
      "sizeInBytes": 1029393,
      "acceptContext": {
      },
      "declineContext": {
      }
    }
  }]
}

次の表で、添付ファイルのコンテンツ プロパティについて説明します。

プロパティ 用途
description ファイルの目的を説明するか、その内容を要約します。
sizeInBytes OneDrive で必要なファイル サイズと容量の見積もりをユーザーに提供します。
acceptContext ユーザーがファイルを受け入れるときにエージェントにサイレントに送信される追加のコンテキスト。
declineContext ユーザーがファイルを拒否したときにエージェントにサイレントに送信される追加のコンテキスト。

ユーザーがファイルを受け入れたときにアクティビティを呼び出す

ユーザーがファイルを受け入れると、呼び出しアクティビティがエージェントに送信されます。 これには、エージェントがPUTを発行してファイルの内容を転送できるOneDrive for Businessプレースホルダー URL が含まれています。 OneDrive URL へのアップロードについては、「アップロード セッションにバイトをアップロードする」をご覧ください。

次のコードは、エージェントが受け取る呼び出しアクティビティの簡潔なバージョンの例を示しています。

{
  "name": "fileConsent/invoke",
  "value": {
    "type": "fileUpload",
    "action": "accept",
    "context": {
    },
    "uploadInfo": {
      "contentUrl": "https://contoso.sharepoint.com/personal/johnadams_contoso_com/Documents/Applications/file_example.txt",
      "name": "file_example.txt",
      "uploadUrl": "https://upload.link",
      "uniqueId": "1150D938-8870-4044-9F2C-5BBDEBA70C8C",
      "fileType": "txt",
      "etag": "123"
    }
  }
}

同様に、ユーザーがファイルを拒否すると、エージェントは、全体的なアクティビティ名が同じ次のイベントを受け取ります。

{
  "name": "fileConsent/invoke",
  "value": {
    "type": "fileUpload",
    "action": "decline",
    "context": {
    }
  }
}

アップロードされたファイルについてユーザーに通知する

ユーザーの OneDrive にファイルをアップロードした後、ユーザーに確認メッセージを送信します。 メッセージには、ユーザーが OneDrive でプレビューまたは開くか、ローカルでダウンロードするために選択できる次の FileCard 添付ファイルが含まれている必要があります。

{
  "attachments": [{
    "contentType": "application/vnd.microsoft.teams.card.file.info",
    "contentUrl": "https://contoso.sharepoint.com/personal/johnadams_contoso_com/Documents/Applications/file_example.txt",
    "name": "file_example.txt",
    "content": {
      "uniqueId": "1150D938-8870-4044-9F2C-5BBDEBA70C8C",
      "fileType": "txt",
    }
  }]
}

次の表で、添付ファイルのコンテンツ プロパティについて説明します。

プロパティ 用途
uniqueId OneDrive または SharePoint ドライブのアイテム ID。
fileType .pdf や .docx などのファイルの種類。

メッセージからインライン イメージをフェッチする

OnMessage ハンドラーを使用して、メッセージの一部であるインライン イメージを取得します。 Teams SDK は認証を自動的に処理するため、アクティビティ コンテキストから添付ファイルのコンテンツの URL に直接アクセスできます。

インライン イメージ

次のコードは、メッセージからインライン イメージを取得する例を示しています。

using Microsoft.Teams.Api;
using Microsoft.Teams.Apps;

WebApplicationBuilder builder = WebApplication.CreateSlimBuilder(args);
builder.Services.AddTeamsBotApplication();

WebApplication app = builder.Build();
TeamsBotApplication teams = app.UseTeamsBotApplication();

teams.OnMessage(async (context, cancellationToken) =>
{
    var attachment = context.Activity.Attachments?[0];
    if (attachment != null && attachment.ContentType.Contains("image"))
    {
        // Download the inline image from the content URL.
        var client = new HttpClient();
        var responseMessage = await client.GetAsync(attachment.ContentUrl);

        // Save the inline image to Files directory.
        var filePath = Path.Combine("Files", "ImageFromUser.png");
        using (var fileStream = new FileStream(filePath, FileMode.Create, FileAccess.Write, FileShare.None))
        {
            await responseMessage.Content.CopyToAsync(fileStream);
        }

        // Create reply with the received image.
        var imageData = Convert.ToBase64String(File.ReadAllBytes(filePath));
        var reply = new MessageActivityInput().WithText(
            $"Attachment of {attachment.ContentType} type and size of {responseMessage.Content.Headers.ContentLength} bytes received.");
        reply.AddAttachment(TeamsAttachment.CreateBuilder()
            .WithContentType("image/png")
            .WithName("ImageFromUser.png")
            .WithContentUrl($"data:image/png;base64,{imageData}")
            .Build());
        await context.SendAsync(reply, cancellationToken);
    }
});

app.Run();

基本的な例

次の例は、同意カードの送信、承認済みと拒否された応答の処理、OneDrive へのファイルのアップロードなど、完全なファイル同意ワークフローを処理する方法を示しています。

次のコードは、ファイル同意カードをユーザーに送信し、受信したファイルを OneDrive にアップロードするためのアクセス許可を要求します。

async Task SendFileConsentCard(Context<MessageActivity> context, string fileName, string fileId, int fileSize, CancellationToken cancellationToken)
{
    var consentContext = new { filename = fileName, file_id = fileId };

    var fileCard = new FileConsentCard
    {
        Description = "This is the file I want to send you",
        SizeInBytes = fileSize,
        AcceptContext = consentContext,
        DeclineContext = consentContext
    };

    var message = new MessageActivityInput()
        .AddAttachment(TeamsAttachment.CreateBuilder()
            .WithContentType(ContentTypeFileConsent)
            .WithName(fileName)
            .WithContent(fileCard)
            .Build());
    await context.SendAsync(message, cancellationToken);
}

ファイルのアップロードを処理する

次のコードは、ユーザーが同意カードを受け取った後、実際のファイルのアップロードを実行し、コンテンツを OneDrive にアップロードし、ファイル情報が添付された成功メッセージを送信します。 C# では、このロジックは OnFileConsent ハンドラー内でインラインで行われます。

async function handleFileUpload(context: any, uploadInfo: FileUploadInfo, fileId: string): Promise<void> {
  try {
    const content = pendingUploads.get(fileId)!;
    pendingUploads.delete(fileId);
    await uploadToOnedrive(uploadInfo.uploadUrl!, content);
    await context.send({
      type: 'message',
      text: `<b>${uploadInfo.name}</b> has been successfully uploaded.`,
      attachments: [{
        content: {
          uniqueId: uploadInfo.uniqueId,
          fileType: uploadInfo.fileType
        },
        contentType: CONTENT_TYPE_FILE_INFO,
        name: uploadInfo.name,
        contentUrl: uploadInfo.contentUrl
      }]
    });
  } catch (e: any) {
    pendingUploads.delete(fileId);
    console.log(`File upload failed: ${e}`);
  }
}

async function uploadToOnedrive(url: string, content: Buffer): Promise<void> {
  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}`);
  }
}

コード サンプル

次のコード サンプルは、ファイルの同意を取得し、エージェントから Teams にファイルをアップロードする方法を示しています。

サンプルの名前 説明 .NET Node.js Python
ファイルのアップロード この Teams 用エージェント サンプルでは、Teams SDK フレームワークを使用したファイル アップロード機能を示します。これにより、ユーザーはファイルをアップロードし、チャット内でインライン画像を表示できます。 表示 表示 表示

関連項目