Bestandsdeling inschakelen met behulp van UI Library in Azure Communication Services Chat met Azure Blob Storage

Belangrijk

Deze functie van Azure Communication Services is momenteel beschikbaar als preview-versie.

Preview-API's en SDK's worden aangeboden zonder een service level agreement. U wordt aangeraden deze niet te gebruiken voor productieworkloads. Sommige functies worden mogelijk niet ondersteund of hebben mogelijk beperkte mogelijkheden.

Raadpleeg aanvullende gebruiksvoorwaarden voor Microsoft Azure Previews voor meer informatie.

In een Azure Communication Services-chat kunnen we het delen van bestanden tussen communicatiegebruikers inschakelen. Azure Communication Services Chat verschilt van de Teams Interoperability Chat ('Interop Chat'). Als u het delen van bestanden in een Interoperabiliteitschat wilt inschakelen, raadpleegt u Delen van bestanden toevoegen met ui-bibliotheek in Teams Interoperability Chat.

In deze zelfstudie configureren we de ui-bibliotheek van Azure Communication Services Voor het delen van bestanden. De ui-bibliotheek chat samengesteld biedt een set uitgebreide onderdelen en UI-besturingselementen die kunnen worden gebruikt om het delen van bestanden in te schakelen. We gebruiken Azure Blob Storage om de opslag in te schakelen van de bestanden die worden gedeeld via de chat-thread.

Belangrijk

Azure Communication Services biedt geen bestandsopslagservice. U moet uw eigen bestandsopslagservice gebruiken voor het delen van bestanden. Voor deze zelfstudie gebruiken we Azure Blob Storage.**

Code downloaden

Open de volledige code voor deze zelfstudie op GitHub. Raadpleeg dit voorbeeld als u het delen van bestanden wilt gebruiken met behulp van UI-onderdelen.

Vereisten

• Een Azure-account met een actief abonnement. Zie Gratis een account maken voor meer informatie.
• Visual Studio Code op een van de ondersteunde platforms.
• Node.js, Active LTS en Maintenance LTS-versies (10.14.1 aanbevolen). Gebruik de opdracht node --version om uw versie te controleren.
• Een actieve Communication Services-resource en verbindingsreeks. Een Communication Services-resource maken.

In deze zelfstudie wordt ervan uitgegaan dat u al weet hoe u een chatcomposiet instelt en uitvoert. U kunt de zelfstudie Chatten samengesteld volgen om te leren hoe u een chatcomposiet instelt en uitvoert.

Overzicht

De UI Library Chat Composite ondersteunt het delen van bestanden door ontwikkelaars in staat te stellen de URL door te geven aan een gehost bestand dat wordt verzonden via de Chatservice van Azure Communication Services. De UI-bibliotheek geeft het bijgevoegde bestand weer en ondersteunt meerdere extensies om het uiterlijk van het verzonden bestand te configureren. Meer specifiek biedt het ondersteuning voor de volgende functies:

1. Knop Bestand bijvoegen voor het kiezen van bestanden via de besturingssysteembestandskiezer
2. Toegestane bestandsextensies configureren.
3. Meerdere uploads in- of uitschakelen.
4. Bestandspictogrammen voor een groot aantal bestandstypen.
5. Kaarten voor het uploaden/downloaden van bestanden met voortgangsindicatoren.
6. Mogelijkheid om elk bestand dynamisch te valideren en fouten weer te geven in de gebruikersinterface.
7. De mogelijkheid om een upload te annuleren en een geüpload bestand te verwijderen voordat het wordt verzonden.
8. Bekijk geüploade bestanden in MessageThread en download ze. Hiermee staat u asynchrone downloads toe.

Het diagram toont een typische stroom van een scenario voor het delen van bestanden voor zowel uploaden als downloaden. In de sectie die is gemarkeerd als Client Managed de bouwstenen waarin ontwikkelaars ze moeten implementeren, worden weergegeven.

Bestandsopslag instellen met behulp van Azure Blob

U kunt de zelfstudie Bestand uploaden naar Azure Blob Storage volgen met een Azure-functie om de back-endcode te schrijven die vereist is voor het delen van bestanden.

Zodra deze is geïmplementeerd, kunt u deze Azure-functie binnen de handleAttachmentSelection functie aanroepen om bestanden te uploaden naar Azure Blob Storage. Voor de rest van de zelfstudie wordt ervan uitgegaan dat u de functie hebt gegenereerd met behulp van de zelfstudie voor Azure Blob Storage die eerder is gekoppeld.

Uw Azure Blob Storage-container beveiligen

In deze zelfstudie wordt ervan uitgegaan dat uw Azure Blob Storage-container openbare toegang biedt tot de bestanden die u uploadt. Het openbaar maken van uw Azure Storage-containers wordt niet aanbevolen voor echte productietoepassingen.

Voor het downloaden van de bestanden uploadt u naar Azure Blob Storage. U kunt handtekeningen voor gedeelde toegang (SAS) gebruiken. Een Shared Access Signature (SAS) biedt beveiligde gedelegeerde toegang tot resources in uw opslagaccount. Met een SAS hebt u gedetailleerde controle over hoe een client toegang heeft tot uw gegevens.

In het downloadbare GitHub-voorbeeld ziet u het gebruik van SAS voor het maken van SAS-URL's voor Azure Storage-inhoud. Daarnaast kunt u meer lezen over SAS.

Voor de UI-bibliotheek moet een React-omgeving worden ingesteld. Vervolgens doen we dat. Als u al een React-app hebt, kunt u deze sectie overslaan.

React-app instellen

We gebruiken de sjabloon create-react-app voor deze quickstart. Zie voor meer informatie: Aan de slag met React

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

cd ui-library-quickstart-composites

Aan het einde van dit proces moet u een volledige toepassing in de map ui-library-quickstart-compositeshebben. Voor deze quickstart wijzigen we bestanden in de src map.

Het pakket installeren

Gebruik de npm install opdracht om de bètainterfacebibliotheek van Azure Communication Services voor JavaScript te installeren.

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

@azure/communication-react hiermee geeft u de kern van Azure Communication Services op peerDependencies , zodat u de API het meest consistent kunt gebruiken vanuit de kernbibliotheken in uw toepassing. U moet deze bibliotheken ook installeren:

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

React-app maken

We gaan de installatie van React App maken testen door het volgende uit te voeren:

npm run start

Chat samengesteld configureren om het delen van bestanden in te schakelen

U moet de variabelewaarden vervangen voor beide algemene variabelen die vereist zijn om de samengestelde chat te initialiseren.

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.
  };

De uploadmethode configureren voor het gebruik van Azure Blob Storage

Als u Het uploaden van Azure Blob Storage wilt inschakelen, wijzigen we de uploadFileToAzureBlob methode die we eerder hebben gedeclareerd met de volgende code. U moet de azure-functiegegevens vervangen om bestanden te uploaden.

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 progress.
      uploadTask.notifyUploadProgressChanged(p.loaded / p.total);
    },
  });

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

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

Foutafhandeling

Wanneer het uploaden mislukt, wordt in ui-bibliotheekchat samengesteld een foutbericht weergegeven.

Hier ziet u voorbeeldcode die laat zien hoe u een upload kunt mislukken vanwege een validatiefout in de grootte:

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
};

Bestandsdownloads - geavanceerd gebruik

Standaard opent de UI-bibliotheek een nieuw tabblad dat verwijst naar de URL die u hebt ingesteld wanneer u notifyUploadCompleted. U kunt ook een aangepaste logica hebben voor het afhandelen van downloads van bijlagen via actionsForAttachment. Laten we eens kijken naar een voorbeeld.

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();
          })
        }
      }
    ];
  }
}

Als er problemen zijn tijdens het downloaden en de gebruiker moet worden gewaarschuwd, kunnen we gewoon throw een fout met een bericht in de onClick functie, dan wordt het bericht weergegeven in de foutbalk boven op de samengestelde chat.

Resources opschonen

Als u een Communication Services-abonnement wilt opschonen en verwijderen, kunt u de resource of resourcegroep verwijderen. Als u de resourcegroep verwijdert, worden ook alle bijbehorende resources verwijderd. Meer informatie over het opschonen van Azure Communication Services-resources en het opschonen van Azure Function-resources.

Volgende stappen

Controleer de rest van de UI-bibliotheek

U wilt mogelijk ook:

• Chat toevoegen aan uw app
• Tokens voor gebruikerstoegang maken
• Meer informatie over de client -en serverarchitectuur
• Meer leren over verificatie
• Bestandsdeling toevoegen met ui-bibliotheek in Teams Interoperability Chat
• Bestandsdeling toevoegen met ui-bibliotheek in Azure Communication Services Chat
• Inlineafbeelding toevoegen met UI-bibliotheek in Teams Interoperability Chat