Aktivera fildelning med hjälp av användargränssnittsbiblioteket i Azure Communication Services Chat med Azure Blob Storage

Viktigt!

Den här funktionen i Azure Communication Services är för närvarande i förhandsversion.

Förhandsversions-API:er och SDK:er tillhandahålls utan ett serviceavtal. Vi rekommenderar att du inte använder dem för produktionsarbetsbelastningar. Vissa funktioner kanske inte stöds, eller så kan de ha begränsade funktioner.

Mer information finns i Kompletterande användningsvillkor för Förhandsversioner av Microsoft Azure.

I en Azure Communication Services-chatt kan vi aktivera fildelning mellan kommunikationsanvändare. Observera att Azure Communication Services Chat skiljer sig från Teams Interoperability Chat ("Interop Chat"). Om du vill aktivera fildelning i en Interop Chat läser du Lägg till fildelning med användargränssnittsbiblioteket i Teams Interoperability Chat.

I den här självstudien konfigurerar vi Azure Communication Services UI Library Chat Composite för att aktivera fildelning. UI Library Chat Composite innehåller en uppsättning omfattande komponenter och användargränssnittskontroller som kan användas för att aktivera fildelning. Vi använder Azure Blob Storage för att aktivera lagring av de filer som delas via chatttråden.

Viktigt!

Azure Communication Services tillhandahåller ingen fillagringstjänst. Du måste använda din egen fillagringstjänst för att dela filer. För den här självstudiekursen använder vi Azure Blob Storage.**

Ladda ned kod

Få åtkomst till den fullständiga koden för den här självstudien på GitHub. Om du vill använda fildelning med hjälp av UI-komponenter refererar du till det här exemplet.

Förutsättningar

• Ett Azure-konto med en aktiv prenumeration. Mer information finns i Skapa ett konto kostnadsfritt.
• Visual Studio Code på någon av plattformarna som stöds.
• Node.js, Active LTS- och Maintenance LTS-versioner (10.14.1 rekommenderas). node --version Använd kommandot för att kontrollera din version.
• En aktiv Communication Services-resurs och anslutningssträng. Skapa en Communication Services-resurs.

Den här självstudien förutsätter att du redan vet hur du konfigurerar och kör en chattkomposit. Du kan följa självstudien Chat Composite för att lära dig hur du konfigurerar och kör en chattkomposit.

Översikt

UI Library Chat Composite stöder fildelning genom att göra det möjligt för utvecklare att skicka URL:en till en värdbaserad fil som skickas via Azure Communication Services chatttjänst. Användargränssnittsbiblioteket renderar den bifogade filen och stöder flera tillägg för att konfigurera utseendet och känslan för den fil som skickas. Mer specifikt stöder den följande funktioner:

1. Knappen Bifoga fil för att välja filer via os-filväljaren
2. Konfigurera tillåtna filnamnstillägg.
3. Aktivera/inaktivera flera uppladdningar.
4. Filikoner för en mängd olika filtyper.
5. Filuppladdnings-/nedladdningskort med förloppsindikatorer.
6. Möjlighet att dynamiskt verifiera varje filuppladdning och visa fel i användargränssnittet.
7. Möjlighet att avbryta en uppladdning och ta bort en uppladdad fil innan den skickas.
8. Visa uppladdade filer i MessageThread och ladda ned dem. Tillåter asynkrona nedladdningar.

Diagrammet visar ett typiskt flöde i ett fildelningsscenario för både uppladdning och nedladdning. Avsnittet som markerats som Client Managed visar byggstenarna där utvecklare behöver implementera dem.

Konfigurera fillagring med Hjälp av Azure Blob

Du kan följa självstudien Ladda upp fil till Azure Blob Storage med en Azure-funktion för att skriva den serverdelskod som krävs för fildelning.

När den har implementerats kan du anropa den här Azure-funktionen i handleAttachmentSelection funktionen för att ladda upp filer till Azure Blob Storage. För resten av självstudien antar vi att du har genererat funktionen med hjälp av självstudien för Azure Blob Storage som länkats tidigare.

Skydda din Azure Blob Storage-container

Den här självstudien förutsätter att din Azure Blob Storage-container ger offentlig åtkomst till de filer som du laddar upp. Att göra dina Azure-lagringscontainrar offentliga rekommenderas inte för verkliga produktionsprogram.

För att ladda ned filerna laddar du upp till Azure Blob Storage, du kan använda signaturer för delad åtkomst (SAS). En signatur för delad åtkomst (SAS) ger säker delegerad åtkomst till resurser i ditt lagringskonto. Med en SAS har du detaljerad kontroll över hur en klient kan komma åt dina data.

Det nedladdningsbara GitHub-exemplet visar användningen av SAS för att skapa SAS-URL:er till Azure Storage-innehåll. Dessutom kan du läsa mer om SAS.

Användargränssnittsbiblioteket kräver att en React-miljö konfigureras. Nu gör vi det. Om du redan har en React-app kan du hoppa över det här avsnittet.

Konfigurera React-appen

Vi använder mallen create-react-app för den här snabbstarten. Mer information finns i: Kom igång med React

npx create-react-app ui-library-quickstart-composites --template typescript

cd ui-library-quickstart-composites

I slutet av den här processen bör du ha ett fullständigt program i mappen ui-library-quickstart-composites. För den här snabbstarten src ändrar vi filer i mappen.

Installera -paketet

npm install Använd kommandot för att installera UI-biblioteket för Beta Azure Communication Services för JavaScript.

npm install @azure/communication-react@1.16.0-beta.1

@azure/communication-react anger centrala Azure Communication Services så peerDependencies att du mest konsekvent kan använda API:et från kärnbiblioteken i ditt program. Du måste också installera dessa bibliotek:

npm install @azure/communication-calling@1.24.1-beta.2
npm install @azure/communication-chat@1.6.0-beta.1

Skapa React-app

Nu ska vi testa installationen av Create React App genom att köra:

npm run start

Konfigurera Chat Composite för att aktivera fildelning

Du måste ersätta variabelvärdena för båda vanliga variabler som krävs för att initiera chattkompositen.

App.tsx

import { initializeFileTypeIcons } from '@fluentui/react-file-type-icons';
import {
  ChatComposite,
  AttachmentUploadTask,
  AttachmentUploadOptions,
  AttachmentSelectionHandler,
  fromFlatCommunicationIdentifier,
  useAzureCommunicationChatAdapter
} from '@azure/communication-react';
import React, { useMemo } from 'react';

initializeFileTypeIcons();

function App(): JSX.Element {
  // Common variables
  const endpointUrl = 'INSERT_ENDPOINT_URL';
  const userId = ' INSERT_USER_ID';
  const displayName = 'INSERT_DISPLAY_NAME';
  const token = 'INSERT_ACCESS_TOKEN';
  const threadId = 'INSERT_THREAD_ID';

  // We can't even initialize the Chat and Call adapters without a well-formed token.
  const credential = useMemo(() => {
    try {
      return new AzureCommunicationTokenCredential(token);
    } catch {
      console.error('Failed to construct token credential');
      return undefined;
    }
  }, [token]);

  // Memoize arguments to `useAzureCommunicationChatAdapter` so that
  // a new adapter is only created when an argument changes.
  const chatAdapterArgs = useMemo(
    () => ({
      endpoint: endpointUrl,
      userId: fromFlatCommunicationIdentifier(userId) as CommunicationUserIdentifier,
      displayName,
      credential,
      threadId
    }),
    [userId, displayName, credential, threadId]
  );
  const chatAdapter = useAzureCommunicationChatAdapter(chatAdapterArgs);

  if (!!chatAdapter) {
    return (
      <>
        <div style={containerStyle}>
          <ChatComposite
            adapter={chatAdapter}
            options={{
              attachmentOptions: {
                uploadOptions: uploadOptions,
                downloadOptions: downloadOptions,
              }
            }} />
        </div>
      </>
    );
  }
  if (credential === undefined) {
    return <h3>Failed to construct credential. Provided token is malformed.</h3>;
  }
  return <h3>Initializing...</h3>;
}

const uploadOptions: AttachmentUploadOptions = {
  // default is false
  disableMultipleUploads: false,
  // define mime types
  supportedMediaTypes: ["image/jpg", "image/jpeg"]
  handleAttachmentSelection: attachmentSelectionHandler,
}

const attachmentSelectionHandler: AttachmentSelectionHandler = async (uploadTasks) => {
  for (const task of uploadTasks) {
    try {
      const uniqueFileName = `${v4()}-${task.file?.name}`;
      const url = await uploadFileToAzureBlob(task);
      task.notifyUploadCompleted(uniqueFileName, url);
    } catch (error) {
      if (error instanceof Error) {
        task.notifyUploadFailed(error.message);
      }
    }
  }
}

const uploadFileToAzureBlob = async (uploadTask: AttachmentUploadTask) => {
  // You need to handle the file upload here and upload it to Azure Blob Storage.
  // This is how you can configure the upload
  // Optionally, you can also update the file upload progress.
  uploadTask.notifyUploadProgressChanged(0.2);
  return {
    url: 'https://sample.com/sample.jpg', // Download URL of the file.
  };

Konfigurera överföringsmetod för att använda Azure Blob Storage

För att aktivera Azure Blob Storage-uppladdning ändrar vi den uploadFileToAzureBlob metod som vi deklarerade tidigare med följande kod. Du måste ersätta Azure-funktionsinformationen för att ladda upp filer.

App.tsx

const uploadFileToAzureBlob = async (uploadTask: AttachmentUploadTask) => {
  const file = uploadTask.file;
  if (!file) {
    throw new Error("uploadTask.file is undefined");
  }

  const filename = file.name;
  const fileExtension = file.name.split(".").pop();

  // Following is an example of calling an Azure Function to handle file upload
  // The https://learn.microsoft.com/azure/developer/javascript/how-to/with-web-app/azure-function-file-upload
  // tutorial uses 'username' parameter to specify the storage container name.
  // the container in the tutorial is private by default. To get default downloads working in
  // this sample, you need to change the container's access level to Public via Azure Portal.
  const username = "ui-library";

  // You can get function url from the Azure Portal:
  const azFunctionBaseUri = "<YOUR_AZURE_FUNCTION_URL>";
  const uri = `${azFunctionBaseUri}&username=${username}&filename=${filename}`;

  const formData = new FormData();
  formData.append(file.name, file);

  const response = await axios.request({
    method: "post",
    url: uri,
    data: formData,
    onUploadProgress: (p) => {
      // Optionally, you can update the file upload progess.
      uploadTask.notifyUploadProgressChanged(p.loaded / p.total);
    },
  });

  const storageBaseUrl = "https://<YOUR_STORAGE_ACCOUNT>.blob.core.windows.net";

  return {
    url: `${storageBaseUrl}/${username}/${filename}`,
  };
};

Felhantering

När en uppladdning misslyckas visas ett felmeddelande i UI Library Chat Composite.

Här är exempelkoden som visar hur du kan misslyckas med en uppladdning på grund av ett storleksverifieringsfel:

App.tsx

import { AttachmentSelectionHandler } from from '@azure/communication-react';

const attachmentSelectionHandler: AttachmentSelectionHandler = async (uploadTasks) => {
  for (const task of uploadTasks) {
    if (task.file && task.file.size > 99 * 1024 * 1024) {
      // Notify ChatComposite about upload failure.
      // Allows you to provide a custom error message.
      task.notifyUploadFailed('File too big. Select a file under 99 MB.');
    }
  }
}

export const attachmentUploadOptions: AttachmentUploadOptions = {
  handleAttachmentSelection: attachmentSelectionHandler
};

Filnedladdningar – avancerad användning

Som standard öppnar användargränssnittsbiblioteket en ny flik som pekar på den URL som du har angett när du notifyUploadCompleted. Du kan också ha en anpassad logik för att hantera nedladdningar av bifogade filer via actionsForAttachment. Låt oss ta en titt på ett exempel.

App.tsx

import { AttachmentDownloadOptions } from "communication-react";

const downloadOptions: AttachmentDownloadOptions = {
  actionsForAttachment: handler
}

const handler = async (attachment: AttachmentMetadata, message?: ChatMessage) => {
   // here we are returning a static action for all attachments and all messages
   // alternately, you can provide custom menu actions based on properties in `attachment` or `message` 
   return [defaultAttachmentMenuAction];
};

const customHandler = = async (attachment: AttachmentMetadata, message?: ChatMessage) => {
   if (attachment.extension === "pdf") {
    return [
      {
        title: "Custom button",
        icon: (<i className="custom-icon"></i>),
        onClick: () => {
          return new Promise((resolve, reject) => {
              // custom logic here
              window.alert("custom button clicked");
              resolve();
              // or to reject("xxxxx") with a custom message
          })
        }
      },
      defaultAttachmentMenuAction
    ];
  } else if (message?.senderId === "user1") {
    return [
      {
        title: "Custom button 2",
        icon: (<i className="custom-icon-2"></i>),
        onClick: () => {
          return new Promise((resolve, reject) => {
            window.alert("custom button 2 clicked");
            resolve();
          })
        }
      },
      // you can also override the default action partially
      {
        ...defaultAttachmentMenuAction,
        onClick: () => {
          return new Promise((resolve, reject) => {
            window.alert("default button clicked");
            resolve();
          })
        }
      }
    ];
  }
}

Om det uppstod några problem under nedladdningen och användaren måste meddelas, kan vi bara throw ett fel med ett meddelande i onClick funktionen så visas meddelandet i felfältet ovanpå Chat Composite.

Rensa resurser

Om du vill rensa och ta bort en Communication Services-prenumeration kan du ta bort resursen eller resursgruppen. Om du tar bort resursgruppen tas även alla andra resurser som är associerade med den bort. Du kan läsa mer om hur du rensar Azure Communication Services-resurser och rensar Azure-funktionsresurser.

Nästa steg

Kontrollera resten av användargränssnittsbiblioteket

Du kanske också vill:

• Lägga till chatt i din app
• Skapa användaråtkomsttoken
• Lär dig mer om klient- och serverarkitektur
• Läs mer om autentisering
• Lägga till fildelning med användargränssnittsbiblioteket i Teams Interoperability Chat
• Lägga till fildelning med användargränssnittsbiblioteket i Azure Communication Services Chat
• Lägga till infogad bild med användargränssnittsbiblioteket i Teams Interoperability Chat