Activer le partage de fichiers à l’aide de la bibliothèque d’interface utilisateur et des Stockage Blob Azure dans une conversation de communication Azure - An Azure Communication Services tutorial

Article
10/04/2023

Important

Cette fonctionnalité d’Azure Communication Services est actuellement en préversion.

Ces interfaces de programmation d’applications et kits de développement logiciel (SDK) en préversion sont fournis sans contrat au niveau du service. Nous vous recommandons de ne pas les utiliser pour les charges de travail de production. Certaines fonctionnalités peuvent être limitées ou non prises en charge.

Pour plus d’informations, consultez Conditions d’utilisation supplémentaires relatives aux préversions de Microsoft Azure.

Dans une conversation Azure Communication Services, nous pouvons activer le partage de fichiers entre les utilisateurs de la communication. Notez que la conversation Azure Communication Services est différente de la conversation d’interopérabilité Teams (« conversation d’interopérabilité »). Si vous souhaitez activer le partage de fichiers dans une conversation interop, reportez-vous à Ajouter le partage de fichiers avec la bibliothèque d’interface utilisateur dans Teams Interoperability Chat.

Dans ce tutoriel, nous configurons le composite de conversation de la bibliothèque d’interface utilisateur Azure Communication Services pour activer le partage de fichiers. Le composite de conversation de la bibliothèque d’interface utilisateur fournit un ensemble riche de composants et de contrôles d’interface utilisateur utilisables pour activer le partage de fichiers. Nous utilisons le Stockage Blob Azure pour activer le stockage des fichiers partagés par le biais du thread de conversation.

Important

Azure Communication Services ne fournit pas de service de stockage de fichiers. Vous devez utiliser votre propre service de stockage de fichiers pour partager des fichiers. Pour les besoins de ce tutoriel, nous utilisons Stockage Blob Azure.**

Télécharger le code

Accédez au code complet de ce tutoriel sur GitHub. Si vous voulez utiliser le partage de fichiers en utilisant des composants d’interface utilisateur, référencez cet exemple.

Prérequis

Compte Azure avec un abonnement actif. Pour plus d’informations, consultez Créer un compte gratuitement
Visual Studio Code sur l’une des plateformes prises en charge.
Node.js, Active LTS et Maintenance LTS (version 10.14.1 recommandée). Utilisez la commande node --version pour vérifier la version que vous utilisez.
Une ressource Communication Services active et la chaîne de connexion. Créer une ressource Communication Services

Ce tutoriel suppose que vous savez déjà configurer et exécuter un composite de conversation. Vous pouvez suivre le tutoriel Composite de conversation pour découvrir comment configurer et exécuter un composite de conversation.

Vue d’ensemble

Le composite de conversation de la bibliothèque d’interface utilisateur prend en charge le partage de fichiers en permettant aux développeurs de passer l’URL à un fichier hébergé envoyé par le biais du service de conversation Azure Communication Services. La bibliothèque d’interface utilisateur affiche le fichier attaché et prend en charge plusieurs extensions pour configurer l’aspect du fichier envoyé. Plus précisément, elle prend en charge les fonctionnalités suivantes :

Bouton Joindre un fichier pour sélectionner des fichiers par le biais du sélecteur de fichiers du système d’exploitation
Configuration des extensions de fichier autorisées.
Activation/Désactivation de plusieurs chargements.
Icônes de fichier pour un large éventail de types de fichiers.
Cartes de chargement/téléchargement de fichiers avec indicateurs de progression.
Possibilité de valider dynamiquement chaque chargement de fichier et d’afficher les erreurs sur l’interface utilisateur.
Possibilité d’annuler un chargement et de supprimer un fichier chargé avant son envoi.
Affichage des fichiers chargés dans MessageThread, téléchargement de ces fichiers. Autorisation des téléchargements asynchrones.

Le diagramme représente un scénario de flux classique de partage de fichiers pour le chargement et le téléchargement. La section marquée comme Client Managed montre les blocs de construction dans lesquels les développeurs doivent les implémenter.

Flux classique de partage de fichiers

Configurer le stockage de fichiers à l’aide de Stockage Blob Azure

Vous pouvez suivre le tutoriel Charger un fichier dans Stockage Blob Azure avec une fonction Azure pour écrire le code back-end nécessaire au partage de fichiers.

Une fois implémentée, vous pouvez appeler cette fonction Azure à l’intérieur de la fonction handleAttachmentSelection pour charger des fichiers dans Stockage Blob Azure. Pour le reste du tutoriel, nous supposons que vous avez généré la fonction à l’aide du tutoriel pour Stockage Blob Azure dont le lien figure précédemment.

Sécurisation de votre conteneur de Stockage Blob Azure

Ce tutoriel part du principe que votre conteneur de stockage blob Azure autorise l’accès public aux fichiers que vous chargez. Permettre à vos conteneurs de stockage Azure d’être publics n’est pas recommandé pour des applications de production réelles.

Pour télécharger les fichiers que vous chargez dans le stockage blob Azure, vous pouvez utiliser des signatures d’accès partagé (SAS). Une signature d’accès partagé (SAS) fournit un accès délégué sécurisé aux ressources de votre compte de stockage. Avec une SAP, vous avez un contrôle granulaire sur la manière dont un client peut accéder à vos données.

L’exemple GitHub téléchargeable présente l’utilisation d’une signature d’accès partagé pour créer des URL SAS dans le contenu du stockage Azure. En outre, vous pouvez en découvrir plus sur SAS.

La bibliothèque d’interface utilisateur nécessite qu’un environnement React soit configuré. Ensuite, nous effectuons cela. Si vous avez déjà eu une application React, vous pouvez ignorer cette section.

Configurer une application React

Dans le cadre de ce guide de démarrage rapide, nous utilisons le modèle create-react-app. Pour plus d'informations, consultez les pages suivantes : Bien démarrer avec React


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

cd ui-library-quickstart-composites

À la fin de ce processus, vous devez disposer d’une application complète dans le dossier ui-library-quickstart-composites. Pour ce guide de démarrage rapide, nous modifions des fichiers se trouvant dans le dossier src.

Installer le package

Utilisez la commande npm install pour installer la bibliothèque d’interface utilisateur Azure Communication Services pour JavaScript.


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

@azure/communication-react spécifie le service Azure Communication Services de base en tant que peerDependencies pour que vous puissiez utiliser l’API de la manière la plus cohérente à partir des bibliothèques principales de votre application. Vous avez besoin d’installer ces bibliothèques également :


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

Créer une application React

Testons l’installation de l’application React créée en exécutant :


npm run start

Vous devez remplacer les valeurs de deux variables courantes nécessaires pour initialiser le composite de conversation.

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

Configurer la méthode de chargement pour utiliser Stockage Blob Azure

Pour activer le chargement Stockage Blob Azure, nous modifions la méthode uploadFileToAzureBlob que nous avons déclarée précédemment avec le code suivant. Vous devez remplacer les informations de la fonction Azure pour activer le chargement.

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

Gestion des erreurs

Quand un chargement échoue, le composite de conversation de la bibliothèque d’interface utilisateur affiche un message d’erreur.

Barre d’erreur de chargement de fichier

Voici un exemple de code illustrant la façon dont vous pouvez faire échouer un chargement en raison d’une erreur de validation de taille :

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

Téléchargements de fichiers – Utilisation avancée

Par défaut, la bibliothèque d’interface utilisateur ouvre un nouvel onglet pointant vers l’URL que vous avez définie lorsque vous notifyUploadCompleted. Vous pouvez également avoir une logique personnalisée pour gérer les téléchargements de pièces jointes via actionsForAttachment. Jetons un coup d’œil sur un exemple.

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

S’il y a eu des problèmes pendant le téléchargement et que l’utilisateur(-trice) doit être averti(e), nous pouvons simplement throw une erreur avec un message dans la fonction onClick, le message s’affiche dans la barre d’erreurs en haut du composite de conversation.

Erreur de téléchargement de fichier

Nettoyer les ressources

Si vous voulez nettoyer et supprimer un abonnement Communication Services, vous pouvez supprimer la ressource ou le groupe de ressources. La suppression du groupe de ressources efface également les autres ressources qui y sont associées. Apprenez-en davantage sur le nettoyage des ressources Azure Communication Services et le nettoyage des ressources Azure Functions.

Étapes suivantes

Vérifier le reste de la bibliothèque d’interface utilisateur

Vous souhaiterez peut-être également :

Partage via

Télécharger le code

Prérequis

Vue d’ensemble

Configurer le stockage de fichiers à l’aide de Stockage Blob Azure

Sécurisation de votre conteneur de Stockage Blob Azure

Configurer une application React

Installer le package

Créer une application React

Configurer la méthode de chargement pour utiliser Stockage Blob Azure

Gestion des erreurs

Téléchargements de fichiers – Utilisation avancée

Nettoyer les ressources

Étapes suivantes

Ressources supplémentaires

Partage via

Activer le partage de fichiers à l’aide de la bibliothèque d’interface utilisateur dans Azure Communication Services Chat avec le stockage Azure Blob

Télécharger le code

Prérequis

Vue d’ensemble

Configurer le stockage de fichiers à l’aide de Stockage Blob Azure

Sécurisation de votre conteneur de Stockage Blob Azure

Configurer une application React

Installer le package

Créer une application React

Configuration du composite de conversation pour activer le partage de fichiers

Configurer la méthode de chargement pour utiliser Stockage Blob Azure

Gestion des erreurs

Téléchargements de fichiers – Utilisation avancée

Nettoyer les ressources

Étapes suivantes

Ressources supplémentaires