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

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

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

Microsoft Graph API の使用

OneDrive および SharePoint 用の Microsoft Graph API を使用して、既存の SharePoint ファイルを参照するカード添付ファイル付きのメッセージを投稿できます。 グラフ API を使用するには、標準の OAuth 2.0 承認フローを使用して、ユーザーの OneDrive フォルダー ( personal ファイルおよび groupchat ファイルの場合) またはチームのチャネル内のファイル ( channel ファイルの場合) へのアクセス権を取得する必要があります。 この方法は、すべての Teams スコープで機能します。

Teams ボット API の使用

ボットは、Teams API を使用して、 personal コンテキスト (個人用チャットとも呼ばれます) でユーザーとファイルを直接送受信できます。 これにより、経費報告、画像認識、ファイル アーカイブ、電子署名、およびファイル コンテンツの直接操作を伴うその他のシナリオを実装できます。 Teams で共有されている Files は通常、カードとして表示され、アプリ内で豊富な表示が可能です。

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

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

ボットでファイルを送受信するには、マニフェストの supportsFiles プロパティを true に設定する必要があります。 このプロパティについては、マニフェスト リファレンスの [bots]/microsoft-365/extensibility/schema/root-bots#supportsfiles) セクションに記載されています。

定義は次のようになります: "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"
    }
  }]
}

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

ベスト プラクティスとして、ユーザーにメッセージを送り返すことによって、ファイルのアップロードを確認する必要があります。

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

ユーザーにファイルをアップロードするには、次の手順を実行します。

1. ファイルの書き込み権限を要求するメッセージをユーザーに送信します。 このメッセージには、アップロードするファイル名が記載された FileConsentCard 添付ファイルが含まれている必要があります。
2. ユーザーがファイルのダウンロードを受け入れると、ボットは場所 URL を含む Invoke アクティビティを受け取ります。
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": {
      }
    }
  }]
}

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

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

ユーザーがファイルを受け入れると、呼び出しアクティビティがボットに送信されます。 これには、ボットが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 ユーザーから委任された API を使用する場合でも、確認メッセージをユーザーに送信する必要があります。 このメッセージには、プレビュー、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",
    }
  }]
}

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

C の基本的な例

次のサンプルは、ボットのダイアログでファイルのアップロードを処理し、ファイルの同意要求を送信する方法を示しています。

// This sample dialog shows two simple flows:
// 1) A silly example of receiving a file from the user, processing the key elements,
//    and then constructing the attachment and sending it back.
// 2) Creating a new file consent card requesting user permission to upload a file.
private async Task MessageReceivedAsync(IDialogContext context, IAwaitable<object> result)
{
    var replyMessage = context.MakeMessage();
    Attachment returnCard;

    var message = await result as Activity;

    // Check to see if the user is sending the bot a file.
    if (message.Attachments != null && message.Attachments.Any())
    {
        var attachment = message.Attachments.First();

        if (attachment.ContentType == FileDownloadInfo.ContentType)
        {
            FileDownloadInfo downloadInfo = (attachment.Content as JObject).ToObject<FileDownloadInfo>();
            if (downloadInfo != null)
            {
                returnCard = CreateFileInfoAttachment(downloadInfo, attachment.Name, attachment.ContentUrl);
                replyMessage.Attachments.Add(returnCard);
            }
        }
    }
    else
    {
        // Illustrates creating a file consent card.
        returnCard = CreateFileConsentAttachment();
        replyMessage.Attachments.Add(returnCard);
    }
    await context.PostAsync(replyMessage);
}


private static Attachment CreateFileInfoAttachment(FileDownloadInfo downloadInfo, string name, string contentUrl)
{
    FileInfoCard card = new FileInfoCard()
    {
        FileType = downloadInfo.FileType,
        UniqueId = downloadInfo.UniqueId
    };

    Attachment att = card.ToAttachment();
    att.ContentUrl = contentUrl;
    att.Name = name;

    return att;
}

private static Attachment CreateFileConsentAttachment()
{
    JObject acceptContext = new JObject();
    // Fill in any additional context to be sent back when the user accepts the file.

    JObject declineContext = new JObject();
    // Fill in any additional context to be sent back when the user declines the file.

    FileConsentCard card = new FileConsentCard()
    {
        AcceptContext = acceptContext,
        DeclineContext = declineContext,
        SizeInBytes = 102635,
        Description = "File description"
    };

    Attachment att = card.ToAttachment();
    att.Name = "Example file";

    return att;
}

関連項目

Microsoft Graph でのファイルの操作