Bagikan melalui

Tutorial: Mengaktifkan dukungan lampiran file di aplikasi Obrolan Anda

SDK Obrolan bekerja dengan mulus dengan Microsoft Teams dalam konteks rapat. Hanya pengguna Teams yang dapat mengirim lampiran file ke pengguna Azure Communication Services. Pengguna Azure Communication Services tidak dapat mengirim lampiran file ke pengguna Teams. Untuk kemampuan saat ini, lihat Obrolan interop Teams.

Menambahkan dukungan lampiran file

SDK Obrolan menyediakan previewUrl properti untuk setiap lampiran file. Secara khusus, previewUrl tautan ke halaman web di SharePoint tempat pengguna dapat melihat konten file, mengedit file, dan mengunduh file jika izin memungkinkan.

Beberapa batasan dikaitkan dengan fitur ini:

  • Admin Teams dari penyewa pengirim dapat memberlakukan kebijakan yang membatasi atau menonaktifkan fitur ini sepenuhnya. Misalnya, admin Teams dapat menonaktifkan izin tertentu (seperti Anyone) yang dapat menyebabkan URL lampiran file (previewUrl) tidak dapat diakses.

  • Saat ini kami hanya mendukung dua izin file:

    • Anyone
    • People you choose (dengan alamat email)

    Beri tahu pengguna Teams Anda bahwa semua izin lain (seperti People in your organization) tidak didukung. Pengguna Teams Anda harus memeriksa kembali untuk memastikan izin default didukung setelah mereka mengunggah file di klien Teams mereka.

  • URL unduhan langsung (url) tidak didukung.

Selain file reguler (dengan AttachmentType ), fileChat SDK juga menyediakan AttachmentType properti .image Pengguna Azure Communication Services dapat melampirkan gambar dengan cara yang mencerminkan perilaku bagaimana klien Microsoft Teams mengonversi lampiran gambar menjadi gambar sebaris di lapisan UI. Untuk informasi selengkapnya, lihat Menangani lampiran gambar.

Pengguna Azure Communication Services dapat menambahkan gambar melalui Unggah dari perangkat ini, yang dirender di sisi Teams dan SDK Obrolan mengembalikan lampiran seperti image. Untuk gambar yang diunggah melalui Lampirkan file cloud, gambar diperlakukan sebagai file reguler di sisi Teams sehingga SDK Obrolan mengembalikan lampiran seperti file.

Perhatikan juga bahwa pengguna Azure Communication Services hanya dapat mengunggah file dengan menggunakan seret dan letakkan atau melalui perintah menu lampiran Unggah dari perangkat ini dan Lampirkan file cloud. Jenis pesan tertentu dengan media yang disematkan (seperti klip video, pesan audio, dan kartu cuaca) saat ini tidak didukung.

Tutorial ini menjelaskan cara mengaktifkan dukungan lampiran file dengan menggunakan SDK Obrolan Azure Communication Services untuk JavaScript.

Kode Sampel

Temukan kode akhir tutorial ini di GitHub.

Prasyarat

Sasaran

  • Render lampiran file di utas pesan. Setiap kartu lampiran file memiliki tombol Buka .
  • Merender lampiran gambar sebagai gambar sebaris.

Menangani lampiran file

SDK Obrolan untuk JavaScript mengembalikan ChatAttachmentType properti file untuk lampiran file reguler dan image untuk gambar yang di-inlin pesan.

export interface ChatMessageReceivedEvent extends BaseChatMessageEvent {
  /**
   * Content of the message.
   */
  message: string;

  /**
   * Chat message attachment.
   */
  attachments?: ChatAttachment[];
  
  ...
}

export interface ChatAttachment {
  /** Id of the attachment */
  id: string;
  /** The type of attachment. */
  attachmentType: AttachmentType;
  /** The name of the attachment content. */
  name?: string;
  /** The URL that is used to provide the original size of the inline images */
  url?: string;
  /** The URL that provides the preview of the attachment */
  previewUrl?: string;
}

/** Type of supported attachments. */
export type ChatAttachmentType = "image" | "file" | "unknown";

Misalnya, JSON berikut menunjukkan seperti apa ChatAttachment tampilan lampiran gambar dan lampiran file:

"attachments": [
    {
        "id": "08a182fe-0b29-443e-8d7f-8896bc1908a2",
        "attachmentType": "file",
        "name": "business report.pdf",
        "previewUrl": "https://contoso.sharepoint.com/:u:/g/user/h8jTwB0Zl1AY"
    },
    {
        "id": "9d89acb2-c4e4-4cab-b94a-7c12a61afe30",
        "attachmentType": "image", 
        "name": "Screenshot.png",
        "url": "https://contoso.communication.azure.com/chat/threads/19:9d89acb29d89acb2@thread.v2/messages/123/images/9d89acb2-c4e4-4cab-b94a-7c12a61afe30/views/original?api-version=2023-11-15-preview",
        "previewUrl": "https://contoso.communication.azure.com/chat/threads/19:9d89acb29d89acb2@thread.v2/messages/123/images/9d89acb2-c4e4-4cab-b94a-7c12a61afe30/views/small?api-version=2023-11-15-preview"
      }
]

Sekarang mari kita kembali ke penanganan aktivitas yang Anda buat di Mulai Cepat: Bergabunglah dengan aplikasi Obrolan Anda ke rapat Teams dan tambahkan beberapa logika tambahan untuk menangani lampiran dengan attachmentType properti file:

chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // Check whether the notification is intended for the current thread
  if (threadIdInput.value != e.threadId) {
     return;
  }
   
  if (e.sender.communicationUserId != userId) {
    renderReceivedMessage(e);
  } else {
    renderSentMessage(e.message);
  }
});

async function renderReceivedMessage(event) {
    messages += `<div class="container lighter"> ${event.message} </div>`;
    messagesContainer.innerHTML = messages;

    // Get the list of attachments and calls renderFileAttachments to construct a file attachment card
    var attachmentHtml = event.attachments
        .filter(attachment => attachment.attachmentType === "file")
        .map(attachment => renderFileAttachments(attachment))
        .join('');
    messagesContainer.innerHTML += attachmentHtml;
}

function renderFileAttachments(attachment) {
    var re = /(?:\.([^.]+))?$/;
    var fileExtension = re.exec(attachment.name)[1];  
    return '<div class="attachment-container">' +
        '<img class="attachment-icon" alt="attachment file icon" />' +
        '<div>' +
        '<p class="attachment-type">' + fileExtension + '</p>' +
        '<p>' + attachment.name + '</p>' +
        '<a href=' + attachment.previewUrl + ' target="_blank" rel="noreferrer">Open</a>' +
        '</div>' +
        '</div>';
}

Pastikan Anda menambahkan beberapa CSS untuk kartu lampiran:

  /* Let's make the chat popup scrollable */
  .chat-popup {

     ...

     max-height: 650px;
     overflow-y: scroll;
}

 .attachment-container {
     overflow: hidden;
     background: #f3f2f1;
     padding: 20px;
     margin: 0;
     border-radius: 10px;
}
 .attachment-container img {
     width: 50px;
     height: 50px;
     float: left;
     margin: 0;
}
 .attachment-container p {
     font-weight: 700;
     margin: 0 5px 20px 0;
}
 .attachment-container {
     display: grid;
     grid-template-columns: 100px 1fr;
     margin-top: 5px;
}
 .attachment-icon {
     content: url("data:image/svg+xml;base64, ...");
}
 .attachment-container a {
     background-color: #dadada;
     color: black;
     font-size: 12px;
     padding: 10px;
     border: none;
     cursor: pointer;
     border-radius: 5px;
     text-align: center;
     margin-right: 10px;
     text-decoration: none;
     margin-top: 10px;
}
 .attachment-container a:hover {
     background-color: black;
     color: white;
}
 .attachment-type {
     position: absolute;
     color: black;
     border: 2px solid black;
     background-color: white;
     margin-top: 50px;
     font-family: sans-serif;
     font-weight: 400;
     padding: 2px;
     text-transform: uppercase;
     font-size: 8px;
}

Itu saja yang Anda butuhkan untuk menangani lampiran file. Selanjutnya, mari kita jalankan kodenya.

Menjalankan kode

Untuk webpack, Anda dapat menggunakan webpack-dev-server properti untuk membuat dan menjalankan aplikasi Anda. Jalankan perintah berikut untuk menggabungkan host aplikasi Anda di server web lokal:

npx webpack-dev-server --entry ./client.js --output bundle.js --debug --devtool inline-source-map

Atau:

npm start

Demo lampiran file

  1. Buka browser Anda, dan buka http://localhost:8080/. Masukkan URL rapat dan ID utas.

  2. Kirim beberapa lampiran file dari klien Teams.

    Cuplikan layar yang memperlihatkan klien Teams dengan pesan terkirim dengan tiga lampiran file.

  3. Anda akan melihat pesan baru yang dirender bersama dengan lampiran file.

    Cuplikan layar yang memperlihatkan aplikasi sampel dengan pesan masuk yang diterima dengan tiga lampiran file.

Menangani lampiran gambar

Lampiran gambar perlu diperlakukan secara berbeda dari lampiran standar file . Lampiran gambar memiliki attachmentType properti image, yang memerlukan token komunikasi untuk mengambil pratinjau atau gambar ukuran penuh.

Sebelum melanjutkan, selesaikan tutorial yang menunjukkan cara mengaktifkan dukungan gambar sebaris di aplikasi Obrolan Anda. Tutorial ini menjelaskan cara mengambil gambar yang memerlukan token komunikasi di header permintaan. Setelah menerima blob gambar, Anda perlu membuat ObjectUrl properti yang menunjuk ke blob ini. Kemudian Anda menyuntikkan URL ini ke src dalam atribut setiap gambar sebaris.

Sekarang setelah Anda terbiasa dengan cara kerja gambar sebaris, Anda dapat merender lampiran gambar seperti gambar sebaris biasa.

Pertama, masukkan image tag ke dalam konten pesan setiap kali ada lampiran gambar:

async function renderReceivedMessage(event) {
    messages += `<div class="container lighter"> ${event.message} </div>`;
    messagesContainer.innerHTML = messages;
    console.log(event);
    // Filter out inline images from attachments
    const imageAttachments = event.attachments?.filter(
        (attachment) =>
        attachment.attachmentType === "image" && !messages.includes(attachment.id)
    );
    // Inject image tag for all image attachments
    var imageAttachmentHtml =
        imageAttachments
        .map((attachment) => renderImageAttachments(attachment))
        .join("") ?? "";
    messagesContainer.innerHTML += imageAttachmentHtml;

    // Get list of attachments and calls renderFileAttachments to construct a file attachment card
    var attachmentHtml =
        event.attachments
        ?.filter((attachment) => attachment.attachmentType === "file")
        .map((attachment) => renderFileAttachments(attachment))
        .join("") ?? "";
    messagesContainer.innerHTML += attachmentHtml;

    // Fetch and render preview images
    fetchPreviewImages(imageAttachments);
}

function renderImageAttachments(attachment) {
    return `<img alt="image" src="" itemscope="png" id="${attachment.id}" style="max-width: 100px">`
}

Sekarang, mari kita pinjam fetchPreviewImages() dari Tutorial: Aktifkan dukungan gambar sebaris dan gunakan apa adanya tanpa perubahan apa pun:

function fetchPreviewImages(attachments) {
    if (!attachments.length > 0) {
        return;
    }
    Promise.all(
        attachments.map(async (attachment) => {
            const response = await fetch(attachment.previewUrl, {
                method: 'GET',
                headers: {
                    'Authorization': 'Bearer ' + tokenString,
                },
            });
            return {
                id: attachment.id,
                content: await response.blob(),
            };
        }),
    ).then((result) => {
        result.forEach((imageRef) => {
            const urlCreator = window.URL || window.webkitURL;
            const url = urlCreator.createObjectURL(imageRef.content);
            document.getElementById(imageRef.id).src = url;
        });
    }).catch((e) => {
        console.log('error fetching preview images');
    });
}

Fungsi ini memerlukan tokenString properti, jadi Anda memerlukan salinan global yang diinisialisasi di init(), seperti yang ditunjukkan dalam cuplikan kode berikut:

var tokenString = '';

async function init() {
    ...
    const {
        token,
        expiresOn
    } = tokenResponse;
    
    tokenString = token;
    ...
}

Sekarang Anda memiliki dukungan lampiran gambar. Lanjutkan menjalankan kode dan melihatnya dalam tindakan.

Demo lampiran gambar

  1. Kirim beberapa lampiran gambar dari klien Teams.

    Cuplikan layar yang memperlihatkan klien Teams memperlihatkan kotak kirim dengan lampiran gambar yang diunggah.

  2. Setelah Anda mengirim lampiran gambar, perhatikan bahwa lampiran tersebut menjadi gambar sebaris di sisi klien Teams.

    Cuplikan layar yang memperlihatkan klien Teams memperlihatkan pesan dengan lampiran gambar yang dikirim ke peserta lain.

  3. Kembali ke aplikasi sampel dan pastikan gambar yang sama dirender.

    Cuplikan layar yang memperlihatkan aplikasi sampel yang memperlihatkan pesan masuk dengan satu gambar sebaris yang dirender.

Tutorial ini menjelaskan cara mengaktifkan dukungan lampiran file dengan menggunakan Azure Communication Services Chat SDK untuk C#.

Dalam tutorial ini, Anda akan mempelajari cara:

  • Menangani lampiran file.
  • Menangani lampiran gambar.

Prasyarat

  • Tinjau mulai cepat Bergabung dengan aplikasi Obrolan Anda ke rapat Teams.
  • Buat sumber daya Azure Communication Services seperti yang dijelaskan dalam Membuat sumber daya Azure Communication Services. Anda perlu merekam string koneksi Anda untuk tutorial ini.
  • Siapkan rapat Teams dengan menggunakan akun bisnis Anda dan siapkan URL rapat.
  • Unduh Chat SDK untuk C# (@azure/communication-chat) 1.3.0 atau yang terbaru. Untuk informasi selengkapnya, lihat Pustaka klien Azure Communication Chat.

Kode Sampel

Temukan kode akhir untuk tutorial ini di GitHub.

Menangani lampiran file

Chat SDK untuk C# mengembalikan ChatAttachmentType properti file untuk lampiran file reguler dan image untuk gambar sebaris.

public readonly partial struct ChatAttachmentType : IEquatable<ChatAttachmentType>
{
        private const string ImageValue = "image";
        private const string FileValue = "file";
        /// <summary> image. </summary>
        public static ChatAttachmentType Image { get; } = new ChatAttachmentType(ImageValue);
        /// <summary> file. </summary>
        public static ChatAttachmentType File { get; } = new ChatAttachmentType(FileValue);
}

Misalnya, JSON berikut menunjukkan seperti apa ChatAttachment tampilan lampiran gambar dan lampiran file saat Anda menerima permintaan dari sisi server:

"attachments": [
    {
        "id": "08a182fe-0b29-443e-8d7f-8896bc1908a2",
        "attachmentType": "file",
        "name": "business report.pdf",
        "previewUrl": "https://contoso.sharepoint.com/:u:/g/user/h8jTwB0Zl1AY"
    },
    {
        "id": "9d89acb2-c4e4-4cab-b94a-7c12a61afe30",
        "attachmentType": "image", 
        "name": "Screenshot.png",
        "url": "https://contoso.communication.azure.com/chat/threads/19:9d89acb29d89acb2@thread.v2/messages/123/images/9d89acb2-c4e4-4cab-b94a-7c12a61afe30/views/original?api-version=2023-11-15-preview",
        "previewUrl": "https://contoso.communication.azure.com/chat/threads/19:9d89acb29d89acb2@thread.v2/messages/123/images/9d89acb2-c4e4-4cab-b94a-7c12a61afe30/views/small?api-version=2023-11-15-preview"
      }
]

Sekarang kembali ke penanganan aktivitas yang Anda buat di mulai cepat sebelumnya dan tambahkan beberapa logika tambahan untuk menangani lampiran dengan ChatAttachmentType properti :file


await foreach (ChatMessage message in allMessages)
{
    // Get message attachments that are of type 'file'
    IEnumerable<ChatAttachment> fileAttachments = message.Content.Attachments.Where(x => x.AttachmentType == ChatAttachmentType.File);
    var chatAttachmentFileUris = new List<Uri>();
    foreach (var file in fileAttachments) 
    {
        chatAttachmentFileUris.Add(file.PreviewUri);
    }

    // Build message list
    if (message.Type == ChatMessageType.Html || message.Type == ChatMessageType.Text)
    {
        textMessages++;
        var userPrefix = message.Sender.Equals(currentUser) ? "[you]:" : "";
        var strippedMessage = StripHtml(message.Content.Message);
      


        var chatAttachments = fileAttachments.Count() > 0 ? "[Attachments]:\n" + string.Join(",\n", chatAttachmentFileUris) : "";
        messageList.Add(long.Parse(message.SequenceId), $"{userPrefix}{strippedMessage}\n{chatAttachments}");
    }
}

Secara khusus, untuk setiap lampiran file, Anda mendapatkan previewUrl properti dan membuat daftar URL di for loop. Kemudian Anda menyematkan string bersama dengan konten pesan Obrolan.

Menangani lampiran gambar

Anda perlu menangani lampiran gambar secara berbeda dari lampiran standar file . Lampiran gambar memiliki ChatAttachmentType properti image, yang memerlukan token komunikasi untuk mengambil pratinjau atau gambar ukuran penuh.

Sebelum melanjutkan, selesaikan tutorial Aktifkan dukungan gambar sebaris. Untuk melampirkan gambar identitas, Anda perlu mencari tahu apakah konten pesan berisi ID gambar yang sama dari lampiran.

bool isImageAttachment = message.Content.Message.Contains(x.Id);

Jika bendera ini benar, maka Anda menerapkan logika gambar sebaris untuk merendernya:

IEnumerable<ChatAttachment> imageAttachments = message.Content.Attachments.Where(x => x.AttachmentType == ChatAttachmentType.Image);
// Fetch image and render
var chatAttachmentImageUris = new List<Uri>();
foreach (ChatAttachment imageAttachment in imageAttachments)
{
    client.DefaultRequestHeaders.Authorization = new System.Net.Http.Headers.AuthenticationHeaderValue("Bearer", communicationTokenCredential.GetToken().Token);
    var response = await client.GetAsync(imageAttachment.PreviewUri);
    var randomAccessStream = await response.Content.ReadAsStreamAsync();
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, async () =>
    {
        var bitmapImage = new BitmapImage();
        await bitmapImage.SetSourceAsync(randomAccessStream.AsRandomAccessStream());
        InlineImage.Source = bitmapImage;
    });
    chatAttachmentImageUris.Add(imageAttachment.PreviewUri);
}

Sekarang aplikasi Anda mendukung lampiran gambar.

Langkah berikutnya