ファイルを送受信する

重要

  • エージェントは、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.acceptfile.consent.declineなど、ファイル同意ワークフローを処理するためのアクティビティ ルートが用意されています。

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

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

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;
using Microsoft.Teams.Plugins.AspNetCore.Extensions;

var builder = WebApplication.CreateBuilder(args);
builder.AddTeams();
var app = builder.Build();
var teams = app.UseTeams();

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 MessageActivity(
            $"Attachment of {attachment.ContentType} type and size of {responseMessage.Content.Headers.ContentLength} bytes received.");
        reply.AddAttachment(new Attachment
        {
            Name = "ImageFromUser.png",
            ContentType = "image/png",
            ContentUrl = $"data:image/png;base64,{imageData}",
        });
        await context.SendAsync(reply, cancellationToken);
    }
});

app.Run();

基本的な例

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

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

async Task SendFileConsentCard<T>(IContext<T> context, string fileName, string fileId, int fileSize)
    where T : IActivity
{
    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 MessageActivity
    {
        Attachments =
        [
            new Attachment
            {
                Content = fileCard,
                ContentType = new ContentType(ContentTypeFileConsent),
                Name = fileName
            }
        ]
    };
    await context.Send(message);
}

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

次のコードは、ユーザーが同意カードを受け入れ、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 Framework を使用してファイルのアップロード機能を示します。これにより、ユーザーはファイルをアップロードし、チャット内のインライン イメージを表示できます。 表示 表示 表示

関連項目