ボットを使用してファイルを送受信する

[アーティクル]
04/17/2023

重要

この記事は、v4 Bot Framework SDK に基づいています。
ボットは、Government Community Cloud High (GCC-High) 環境と国防総省 (DOD) 環境でのファイルの送受信をサポートしていません。

ボットからファイルを送受信するには、次の 2 つの方法があります。

Microsoft Graph API を使用する: このメソッドは、すべてのMicrosoft Teams スコープ内のボットに対して機能します。
- personal
- channel
- groupchat
Teams ボット API を使用する: これらは personal コンテキスト内のファイルのみをサポートします。

次のビデオは、ボットがファイルの送受信プロセスを簡単かつ効率的に簡素化する方法を示しています。

Graph API を使用する

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

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

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

または、Teams ボット API を使用して、ボットとの間でファイルを送受信することもできます。

Teams ボット API を使用する

Teams ボット API は personal コンテキストでのみ機能します。これらは、 channel または groupchat コンテキストでは機能しません。

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

次のセクションでは、メッセージの送信など、ユーザーとの直接的なやり取りとしてファイルコンテンツを送信する方法について説明します。この API は、Teams ボットプラットフォームの一部として提供されます。

ファイルをサポートするようにボットを構成する

ボットでファイルを送受信するには、マニフェストの 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 などのファイルの種類。

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

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

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

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

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

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

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

モバイルでファイルをアップロードするためのユーザーアクセス許可を要求するカード同意する

{
  "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 などのファイルの種類。

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

ボットのアクセストークンを使用して、メッセージの一部であるインラインイメージをフェッチします。

インラインイメージ

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

private async Task ProcessInlineImage(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var attachment = turnContext.Activity.Attachments[0];
    var client = _clientFactory.CreateClient();
    // Get Bot's access token to fetch inline image. 
    var token = await new MicrosoftAppCredentials(microsoftAppId, microsoftAppPassword).GetTokenAsync();
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
    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 image.
    var reply = MessageFactory.Text($"Attachment of {attachment.ContentType} type and size of {responseMessage.Content.Headers.ContentLength} bytes received.");
    reply.Attachments = new List<Attachment>() { 
        GetInlineAttachment() 
    };
    await turnContext.SendActivityAsync(reply, cancellationToken);
}
private static Attachment GetInlineAttachment()
{
    var imagePath = Path.Combine("Files", "ImageFromUser.png");
    var imageData = Convert.ToBase64String(File.ReadAllBytes(imagePath));
    return new Attachment
    {
        Name = @"ImageFromUser.png",
        ContentType = "image/png",
        ContentUrl = $"data:image/png;base64,{imageData}",
    };
}

C# の基本的な例

次のコードは、ボットのダイアログでファイルのアップロードを処理し、ファイルの同意リクエストを送信する方法の例を示しています。


protected override async Task OnMessageActivityAsync(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    if (turnContext.Activity.Attachments?[0].ContentType.Contains("image/*") == true)
    {
        // Inline image.
        await ProcessInlineImage(turnContext, cancellationToken);
    }
    else
    {
        string filename = "teams-logo.png";
        string filePath = Path.Combine("Files", filename);
        long fileSize = new FileInfo(filePath).Length;
        await SendFileCardAsync(turnContext, filename, fileSize, cancellationToken);
    }
}
private async Task ProcessInlineImage(ITurnContext<IMessageActivity> turnContext, CancellationToken cancellationToken)
{
    var attachment = turnContext.Activity.Attachments[0];
    var client = _clientFactory.CreateClient();
    // Get Bot's access token to fetch inline image. 
    var token = await new MicrosoftAppCredentials(microsoftAppId, microsoftAppPassword).GetTokenAsync();
    client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", token);
    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 image.
    var reply = MessageFactory.Text($"Attachment of {attachment.ContentType} type and size of {responseMessage.Content.Headers.ContentLength} bytes received.");
    reply.Attachments = new List<Attachment>() { GetInlineAttachment() };
    await turnContext.SendActivityAsync(reply, cancellationToken);
}
private static Attachment GetInlineAttachment()
{
    var imagePath = Path.Combine("Files", "ImageFromUser.png");
    var imageData = Convert.ToBase64String(File.ReadAllBytes(imagePath));
    return new Attachment
    {
        Name = @"ImageFromUser.png",
        ContentType = "image/png",
        ContentUrl = $"data:image/png;base64,{imageData}",
    };
}
private async Task SendFileCardAsync(ITurnContext turnContext, string filename, long filesize, CancellationToken cancellationToken)
{
    var consentContext = new Dictionary<string, string>
    {
        { 
            "filename", filename 
        },
    };
    var fileCard = new FileConsentCard
    {
        Description = "This is the file I want to send you",
        SizeInBytes = filesize,
        AcceptContext = consentContext,
        DeclineContext = consentContext,
    };
    var asAttachment = new Attachment
    {
        Content = fileCard,
        ContentType = FileConsentCard.ContentType,
        Name = filename,
    };
    var replyActivity = turnContext.Activity.CreateReply();
    replyActivity.Attachments = new List<Attachment>() { asAttachment };
    await turnContext.SendActivityAsync(replyActivity, cancellationToken);
}

コードサンプル

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

サンプルの名前	説明	.NET	Node.js	Python	マニフェスト
ファイルのアップロード	このサンプルでは、ボットを使用してファイルの同意を取得し、Teams にファイルをアップロードする方法を示します。また、ボットに送信されたファイルを受信する方法についても説明します。	表示	表示	表示	表示

ステップバイステップのガイド

ステップバイステップガイドに従って、ボットを使用して Teams にファイルをアップロードします。

次のステップ

Teams でレートを制限してボットを最適化する

次の方法で共有

ボットを使用してファイルを送受信する

Graph API を使用する

Teams ボット API を使用する

ファイルをサポートするようにボットを構成する

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

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

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

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

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

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

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

C# の基本的な例

コードサンプル

ステップバイステップのガイド

次のステップ

関連項目

その他のリソース

次の方法で共有

ボットを使用してファイルを送受信する

Graph API を使用する

Teams ボット API を使用する

ファイルをサポートするようにボットを構成する

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

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

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

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

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

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

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

C# の基本的な例

コード サンプル

ステップ バイ ステップのガイド

次のステップ

関連項目

その他のリソース

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

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

コードサンプル

ステップバイステップのガイド