Démarrage rapide : Ajouter un système de conversation à votre application

Prérequis

• Compte Azure avec un abonnement actif. Créez un compte gratuitement.

• Une ressource Communication Services active et la chaîne de connexion. Créer une ressource Communication Services

• Installez Azure CLI.

• Prenez note de votre point de terminaison de ressource Communication Services. Vous pouvez obtenir ce point de terminaison auprès du portail Azure. Vous pouvez aussi trouver l’URL du point de terminaison dans la chaîne de connexion. C’est l’URL qui vient après endpoint= et qui commence par https://.

• Jeton d’accès utilisateur. Veillez à définir l’étendue sur chat (conversation) et prenez note de la chaîne du jeton et de la chaîne user_id. Vous pouvez également utiliser Azure CLI et exécuter la commande ci-dessous avec votre chaîne de connexion pour créer un utilisateur et un jeton d’accès.

  az communication identity token issue --scope chat --connection-string "yourConnectionString"
  

  Pour plus d’informations, consultez Utiliser Azure CLI pour créer et gérer des jetons d’accès.

Configuration

Ajouter l’extension

Ajoutez l’extension Azure Communication Services pour Azure CLI à l’aide de la commande az extension.

az extension add --name communication

Connectez-vous à Azure CLI

Vous devez vous connecter à Azure CLI. Vous pouvez vous connecter en exécutant la commande az login à partir du terminal et fournir vos informations d’identification.

(Facultatif) Utiliser les opérations d’identité Azure CLI sans passer un point de terminaison ou un jeton d’accès

Stocker votre point de terminaison dans une variable d’environnement

Vous pouvez configurer la variable d’environnement AZURE_COMMUNICATION_ENDPOINT pour utiliser les opérations de conversation Azure CLI sans avoir à utiliser --endpoint pour passer le point de terminaison. Pour configurer une variable d’environnement, ouvrez une fenêtre de console, puis sélectionnez votre système d’exploitation dans les onglets ci-dessous. Remplacez <yourEndpoint> par votre point de terminaison réel.

setx AZURE_COMMUNICATION_ENDPOINT "<yourEndpoint>"

export AZURE_COMMUNICATION_ENDPOINT="<yourEndpoint>"

export AZURE_COMMUNICATION_ENDPOINT="<yourEndpoint>"

Stocker votre jeton d’accès dans une variable d’environnement

Vous pouvez configurer la variable d’environnement AZURE_COMMUNICATION_ACCESS_TOKEN pour utiliser les opérations de conversation Azure CLI sans avoir à utiliser --access-token pour passer le jeton d’accès. Pour configurer une variable d’environnement, ouvrez une fenêtre de console, puis sélectionnez votre système d’exploitation dans les onglets ci-dessous. Remplacez <yourAccessToken> par votre jeton d’accès réel.

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

Opérations

Démarrer un fil de conversation

Utilisez la commande thread create pour créer un thread de conversation.

az communication chat thread create --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"

Si vous avez stocké le point de terminaison et le jeton d’accès dans des variables d’environnement comme indiqué ci-dessus, vous n’avez pas besoin de les passer à la commande.

az communication chat thread create --topic "<chatTopic>"

• Utilisez <chatTopic> pour attribuer un thème à ce fil de conversation. Vous pouvez mettre à jour le thème après la création du thread de conversation en utilisant la commande thread update-topic.
• Remplacez <endpoint> par votre point de terminaison Azure Communication Services.
• Remplacez <token> par votre jeton d’accès obtenu précédemment en exécutant la commande identity token issue.

Mettre à jour le sujet d’un fil de conversation

az communication chat thread update-topic --thread "<chatThreadId>" --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"

• Remplacez <chatThreadId> par votre ID de thread de conversation.
• Remplacez <chatTopic> par le nouveau thème de conversation que vous voulez définir.
• Remplacez <endpoint> par votre point de terminaison Azure Communication Services.
• Remplacez <token> par votre jeton d’accès obtenu précédemment en exécutant la commande identity token issue.

Répertorier tous les fils de conversation

La commande thread list retourne la liste des threads de conversation d’un utilisateur.

az communication chat thread list --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"

• Utilisez éventuellement <startTime> pour spécifier le point dans le temps le plus ancien pour obtenir les messages de la conversation.
• Remplacez <endpoint> par votre point de terminaison Azure Communication Services.
• Remplacez <token> par votre jeton d’accès obtenu précédemment en exécutant la commande identity token issue.

Envoyer un message à un fil de conversation

Utilisez la commande message send pour envoyer un message à un thread de conversation que vous avez créé, identifié par threadId.

az communication chat message send --thread "<chatThreadId>" --display-name "<displayName>" --content "<content>" --message-type "<messageType>"  --endpoint "<endpoint>" --access-token "<token>"

• Remplacez <chatThreadId> par votre ID de thread de conversation.
• Utilisez <content> pour fournir le contenu du message de conversation.
• Utilisez <messageType> pour spécifier le type de contenu du message. Les valeurs possibles sont text et html. Si vous ne spécifiez aucune valeur, la valeur par défaut est text.
• Utiliser éventuellement <displayName> pour spécifier le nom d’affichage de l’expéditeur.
• Remplacez <endpoint> par votre point de terminaison Azure Communication Services.
• Remplacez <token> par votre jeton d’accès obtenu précédemment en exécutant la commande identity token issue.

Lister les messages de conversation d’un thread de conversation

La commande message list retourne la liste des messages de conversation dans un thread de conversation.

az communication chat message list --thread "<chatThreadId>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"

• Remplacez <chatThreadId> par votre ID de thread de conversation.
• Utilisez éventuellement <startTime> pour spécifier le point dans le temps le plus ancien pour obtenir les messages de la conversation.
• Remplacez <endpoint> par votre point de terminaison Azure Communication Services.
• Remplacez <token> par votre jeton d’accès obtenu précédemment en exécutant la commande identity token issue.

Recevoir un message de conversation d’un thread de conversation

Vous pouvez récupérer des messages de conversation en utilisant la commande message list.

az communication chat message get --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"

• Remplacez <chatThreadId> par votre ID de thread de conversation.
• Remplacez <messageId> par l’ID du message que vous voulez récupérer.
• Remplacez <endpoint> par votre point de terminaison Azure Communication Services.
• Remplacez <token> par votre jeton d’accès obtenu précédemment en exécutant la commande identity token issue.

Envoyer une confirmation de lecture

Vous utilisez la commande message receipt send pour publier un événement de confirmation de lecture sur un thread pour le compte d’un utilisateur.

az communication chat message receipt send --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"

• Remplacez <chatThreadId> par votre ID de thread de conversation.
• Remplacez <messageId> pour spécifier l’ID du dernier message lu par l’utilisateur actuel.
• Remplacez <endpoint> par votre point de terminaison Azure Communication Services.
• Remplacez <token> par votre jeton d’accès obtenu précédemment en exécutant la commande identity token issue.

Ajouter un utilisateur comme participant au fil de conversation

Quand vous créez un fil de conversation, vous pouvez y ajouter des utilisateurs et en supprimer. En ajoutant des utilisateurs, vous leur octroyez l’accès permettant d’envoyer des messages au fil de conversation et d’ajouter ou de supprimer d’autres participants. Avant d’appeler la commande participant add, vérifiez que vous avez acquis un nouveau jeton d’accès et une identité pour cet utilisateur.

az communication chat participant add --thread "<chatThreadId>" --user "<userId>" --display-name "<displayName>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"

• Remplacez <chatThreadId> par votre ID de thread de conversation.
• Remplacez <userId> par votre userId.
• Utiliser éventuellement <displayName> pour spécifier le nom d’affichage de l’expéditeur.
• Utilisez éventuellement <startTime> pour spécifier le point dans le temps le plus ancien pour obtenir les messages de la conversation.
• Remplacez <endpoint> par votre point de terminaison Azure Communication Services.
• Remplacez <token> par votre jeton d’accès obtenu précédemment en exécutant la commande identity token issue.

Répertorier les participants d’un fil de conversation

De la même façon que vous ajoutez un participant, vous pouvez également répertorier les participants d’une conversation.

Utilisez la commande participant list pour récupérer les participants à la conversation.

az communication chat participant list --thread "<chatThreadId>" --skip "<skip>" --endpoint "<endpoint>" --access-token "<token>"

• Remplacez <chatThreadId> par votre ID de thread de conversation.
• Utilisez éventuellement <skip> pour ignorer les participants jusqu’à une position spécifiée dans la réponse.
• Remplacez <endpoint> par votre point de terminaison Azure Communication Services.
• Remplacez <token> par votre jeton d’accès obtenu précédemment en exécutant la commande identity token issue.

Supprimer un participant d’un thread de conversation

Vous pouvez supprimer un participant de conversation d’un thread de conversation en utilisant la commande « participant remove ».

az communication chat participant remove --thread "<chatThreadId>" --user "<userId>" --endpoint "<endpoint>" --access-token "<token>"

• Remplacez <chatThreadId> par votre ID de thread de conversation.
• Remplacez <userId> par l’ID d’utilisateur que vous voulez supprimer du thread de conversation.
• Remplacez <endpoint> par votre point de terminaison Azure Communication Services.
• Remplacez <token> par votre jeton d’accès obtenu précédemment en exécutant la commande identity token issue.

Prérequis

Avant de commencer, assurez-vous de :

• Créer un compte Azure avec un abonnement actif. Pour plus d’informations, consultez Créer un compte gratuitement.

• Installez Node.js, versions Active LTS et Maintenance LTS.

• Créer une ressource Azure Communication Services. Pour plus d’informations, consultez Créer des ressources Azure Communication Services. Vous devez enregistrer le point de terminaison et la chaîne de connexion de votre ressource pour ce guide de démarrage rapide.

• Créez trois utilisateurs Azure Communication Services et émettez pour eux un Jeton d’accès utilisateur. Veillez à définir l’étendue sur chat (conversation) et prenez note de la chaîne du jeton et de la chaîne user_id. La démonstration complète crée un fil avec deux participants initiaux, puis ajoute un troisième participant au fil. Vous pouvez également utiliser Azure CLI et exécuter la commande ci-dessous avec votre chaîne de connexion pour créer un utilisateur et un jeton d’accès.

  az communication identity token issue --scope chat --connection-string "yourConnectionString"
  

  Pour plus d’informations, consultez Utiliser Azure CLI pour créer et gérer des jetons d’accès.

Configuration

Créer une application web

Pour commencer, ouvrez votre terminal ou votre fenêtre Commande pour créer un répertoire pour votre application, puis accédez-y.

mkdir chat-quickstart && cd chat-quickstart

Exécutez npm init -y pour créer un fichier package.json avec les paramètres par défaut.

npm init -y

Installer les packages

Utilisez la commande npm install pour installer les kits de développement logiciel (SDK) Communication Services pour JavaScript ci-dessous.

npm install @azure/communication-common --save

npm install @azure/communication-identity --save

npm install @azure/communication-signaling --save

npm install @azure/communication-chat --save

L’option --save liste la bibliothèque comme dépendance dans votre fichier package.json.

Configurer le framework d’application

Ce guide de démarrage rapide utilise un paquet pour regrouper les ressources de l’application. Exécutez la commande suivante pour l’installer et la répertorier en tant que dépendance de développement dans votre Package. JSON :

npm install parcel --save-dev

Créez un fichier index.html dans le répertoire racine de votre projet. Nous nous servirons de ce fichier de modèle pour ajouter la fonctionnalité de conversation (chat) avec le kit de développement logiciel (SDK) Azure Communication Chat pour JavaScript.

<!DOCTYPE html>
<html>
  <head>
    <title>Communication Client - Chat Sample</title>
  </head>
  <body>
    <h4>Azure Communication Services</h4>
    <h1>Chat Quickstart</h1>
    <script src="./client.js" type="module"></script>
  </body>
</html>

Créez un fichier dans le répertoire racine de votre projet sous le nom client.js qui contiendra la logique d’application pour ce démarrage rapide.

Créer un client de conversation

Pour créer un client de conversation dans votre application web, vous allez utiliser le point de terminaison Communication Services, ainsi que le jeton d’accès qui a été généré au cours des étapes prérequises.

Les jetons d’accès utilisateur vous permettent de créer des applications clientes qui s’authentifient directement auprès d’Azure Communication Services. Ce guide de démarrage rapide n’aborde pas la création d’un niveau de service pour gérer les jetons de votre application de conversation. Consultez Concepts relatifs aux conversations pour en savoir plus sur l’architecture des conversations, et consultez Jetons d’accès utilisateur pour en savoir plus sur les jetons d’accès.

Dans client.js, utilisez le point de terminaison et le jeton d’accès dans le code ci-dessous pour ajouter une fonctionnalité de conversation en utilisant le kit de développement logiciel (SDK) Azure Communication Chat pour JavaScript.

import { ChatClient } from '@azure/communication-chat';
import { AzureCommunicationTokenCredential } from '@azure/communication-common';

// Your unique Azure Communication service endpoint
let endpointUrl = '<replace with your resource endpoint>';
// The user access token generated as part of the pre-requisites
let userAccessToken = '<USER_ACCESS_TOKEN>';

let chatClient = new ChatClient(endpointUrl, new AzureCommunicationTokenCredential(userAccessToken));
console.log('Azure Communication Chat client created!');

• Remplacez endpointUrl par le point de terminaison de ressource Communication Services. Si vous ne l’avez pas encore fait, consultez Créer une ressource Azure Communication Services.
• Remplacez userAccessToken par le jeton que vous avez émis.

Exécuter le code

Utilisez la commande suivante pour exécuter votre application :

npx parcel index.html

Ouvrez votre navigateur et accédez à l’adresse http://localhost:1234/.. Dans la console d’outils de développement de votre navigateur, vous devez voir les informations suivantes :

Azure Communication Chat client created!

Modèle objet

Les classes et interfaces suivantes gèrent quelques-unes des principales fonctionnalités du kit de développement logiciel (SDK) Azure Communication Services Chat pour JavaScript.

Démarrer un fil de conversation

Utilisez la méthode createThread pour créer un fil de conversation.

createThreadRequest est utilisé pour décrire la demande de fil :

• Utilisez topic pour attribuer un sujet à cette conversation. Les sujets peuvent être mis à jour après la création du thread de conversation à l’aide de la fonction UpdateThread.
• Utilisez participants pour lister les participants à ajouter au fil de conversation.

Une fois résolue, la méthode createChatThread retourne une CreateChatThreadResult. Ce modèle contient une propriété chatThread où vous pouvez accéder à l’id du fil nouvellement créé. Vous pouvez ensuite utiliser l’id pour obtenir une instance de ChatThreadClient. Le ChatThreadClient peut ensuite être utilisé pour effectuer une opération dans le fil, comme envoyer des messages ou lister les participants.

async function createChatThread() {
  const createChatThreadRequest = {
    topic: "Hello, World!"
  };
  const createChatThreadOptions = {
    participants: [
      {
        id: { communicationUserId: '<USER_ID>' },
        displayName: '<USER_DISPLAY_NAME>'
      }
    ]
  };
  const createChatThreadResult = await chatClient.createChatThread(
    createChatThreadRequest,
    createChatThreadOptions
  );
  const threadId = createChatThreadResult.chatThread.id;
  return threadId;
}

createChatThread().then(async threadId => {
  console.log(`Thread created:${threadId}`);
  // PLACEHOLDERS
  // <CREATE CHAT THREAD CLIENT>
  // <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD>
  // <SEND MESSAGE TO A CHAT THREAD>
  // <LIST MESSAGES IN A CHAT THREAD>
  // <ADD NEW PARTICIPANT TO THREAD>
  // <LIST PARTICIPANTS IN A THREAD>
  // <REMOVE PARTICIPANT FROM THREAD>
  });

Quand vous actualisez l’onglet du navigateur, la console doit montrer les éléments suivants :

Thread created: <thread_id>

Obtenir un client de fil de conversation

La méthode getChatThreadClient retourne un chatThreadClient pour un fil qui existe déjà. Elle peut être utilisée pour effectuer des opérations sur le fil créé : ajout de participants, envoi d’un message, etc. threadId est l’ID unique du fil de conversation existant.

let chatThreadClient = chatClient.getChatThreadClient(threadId);
console.log(`Chat Thread client for threadId:${threadId}`);

Ajoutez ce code à la place du commentaire <CREATE CHAT THREAD CLIENT> dans client.js, actualisez l’onglet du navigateur et examinez la console, qui doit présenter les éléments suivants :

Chat Thread client for threadId: <threadId>

Répertorier tous les fils de conversation

La méthode listChatThreads retourne un objet PagedAsyncIterableIterator de ChatThreadItem. Celui-ci peut être utilisé pour répertorier tous les fils de conversation. Un itérateur de [ChatThreadItem] est la réponse retournée par l’énumération des threads

const threads = chatClient.listChatThreads();
for await (const thread of threads) {
   // your code here
}

Envoyer un message à un fil de conversation

Utilisez la méthode sendMessage pour envoyer un message à un fil identifié par threadId.

sendMessageRequest est utilisé pour décrire la demande de message :

• Utilisez content pour fournir le contenu du message de conversation ;

sendMessageOptions sert à décrire les paramètres facultatifs de l’opération :

• Utilisez senderDisplayName pour spécifier le nom d’affichage de l’expéditeur ;
• Utilisez type pour spécifier le type de message, par exemple « text » ou « html » ;
• Utilisez metadata (facultatif) pour inclure toute autre donnée que vous souhaitez envoyer avec le message. Ce champ constitue un mécanisme permettant aux développeurs d’étendre les fonctionnalités des messages de conversation et d’ajouter des informations personnalisées selon le cas d’usage. Par exemple, si vous partagez un lien de fichier dans le message, vous avez la possibilité d’ajouter « hasAttachment:true » dans les métadonnées pour que l’application du destinataire puisse l’analyser et l’afficher en conséquence.

SendChatMessageResult est la réponse retournée à la suite de l’envoi du message; elle contient un ID, qui est l’ID unique du message.

const sendMessageRequest =
{
  content: 'Please take a look at the attachment'
};
let sendMessageOptions =
{
  senderDisplayName : 'Jack',
  type: 'text',
  metadata: {
    'hasAttachment': 'true',
    'attachmentUrl': 'https://contoso.com/files/attachment.docx'
  }
};
const sendChatMessageResult = await chatThreadClient.sendMessage(sendMessageRequest, sendMessageOptions);
const messageId = sendChatMessageResult.id;
console.log(`Message sent!, message id:${messageId}`);

Ajoutez ce code à la place du commentaire <SEND MESSAGE TO A CHAT THREAD> dans client.js, actualisez l’onglet du navigateur et examinez la console.

Message sent!, message id:<number>

Recevoir les messages de conversation d’un fil de conversation

Avec la signalisation en temps réel, vous pouvez vous abonner pour écouter les nouveaux messages entrants et mettre à jour en conséquence les messages actuellement en mémoire. Azure Communication Services prend en charge une liste d’événements auxquels vous pouvez vous abonner.

// open notifications channel
await chatClient.startRealtimeNotifications();
// subscribe to new notification
chatClient.on("chatMessageReceived", (e) => {
  console.log("Notification chatMessageReceived!");
  // your code here
});

Ajoutez ce code à la place du commentaire <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD> dans client.js. Si vous actualisez l’onglet du navigateur, la console doit présenter un message Notification chatMessageReceived ;

Vous pouvez aussi récupérer les messages de conversation en interrogeant la méthode listMessages selon des intervalles définis.

const messages = chatThreadClient.listMessages();
for await (const message of messages) {
   // your code here
}

Ajoutez ce code à la place du commentaire <LIST MESSAGES IN A CHAT THREAD> dans client.js. Si vous actualisez l’onglet, la liste des messages envoyés dans ce fil de conversation doit apparaître dans la console.

listMessages retourne différents types de messages, qui peuvent être identifiés par chatMessage.type.

Pour plus d’informations, consultez Types de messages.

Ajouter un utilisateur comme participant au fil de conversation

Une fois qu’un fil de conversation est créé, vous pouvez y ajouter des utilisateurs et en supprimer. En ajoutant des utilisateurs, vous leur permettez d’envoyer des messages au fil de conversation et d’ajouter/supprimer d’autres participants.

Avant d’appeler la méthode addParticipants, vérifiez que vous avez acquis un nouveau jeton d’accès et une identité pour cet utilisateur. L’utilisateur aura besoin de ce jeton d’accès pour initialiser son client de conversation.

addParticipantsRequest décrit l’objet de demande où participants liste les participants à ajouter au fil de conversation ;

• id, obligatoire, est l’identificateur de communication à ajouter au fil de conversation.
• displayName, facultatif, est le nom d’affichage pour le participant au fil.
• shareHistoryTime, facultatif, est le moment à partir duquel l’historique de conversation est partagé avec le participant. Pour partager l’historique depuis le début du fil de conversation, attribuez à cette propriété une date égale ou antérieure à la date de création du fil. Pour ne pas partager l’historique antérieur au moment où le participant a été ajouté, définissez-la sur l’heure actuelle. Pour partager l’historique partiel, attribuez-lui la date de votre choix.

const addParticipantsRequest =
{
  participants: [
    {
      id: { communicationUserId: '<NEW_PARTICIPANT_USER_ID>' },
      displayName: 'Jane'
    }
  ]
};

await chatThreadClient.addParticipants(addParticipantsRequest);

Remplacez NEW_PARTICIPANT_USER_ID par un nouvel ID d’utilisateur. Ajoutez ce code à la place du commentaire <ADD NEW PARTICIPANT TO THREAD> dans client.js.

Lister les utilisateurs dans un fil de conversation

const participants = chatThreadClient.listParticipants();
for await (const participant of participants) {
   // your code here
}

Ajoutez ce code à la place du commentaire <LIST PARTICIPANTS IN A THREAD> dans client.js, actualisez l’onglet du navigateur et examinez la console, qui doit afficher des informations sur les utilisateurs présents dans un fil.

Supprimer un utilisateur d’un fil de conversation

De la même façon que vous ajoutez un participant, vous pouvez supprimer des participants d’un fil de conversation. Pour pouvoir effectuer une suppression, vous devez suivre les ID des participants que vous avez ajoutés.

Utilisez la méthode removeParticipant où participant est l’utilisateur de communication à supprimer du fil.

await chatThreadClient.removeParticipant({ communicationUserId: <PARTICIPANT_ID> });
await listParticipants();

Remplacez PARTICIPANT_ID par un ID d’utilisateur utilisé à l’étape précédente (<NEW_PARTICIPANT_USER_ID>). Ajoutez ce code à la place du commentaire <REMOVE PARTICIPANT FROM THREAD> dans client.js.

S’abonner à l’état de la connexion des notifications en temps réel

L’abonnement aux événements realTimeNotificationConnected et realTimeNotificationDisconnected vous permet de savoir quand la connexion au serveur d’appels est active.

// subscribe to realTimeNotificationConnected event
chatClient.on('realTimeNotificationConnected', () => {
  console.log("Real time notification is now connected!");
  // your code here
});
// subscribe to realTimeNotificationDisconnected event
chatClient.on('realTimeNotificationDisconnected', () => {
  console.log("Real time notification is now disconnected!");
  // your code here
});

Exemple de code

Vous trouverez le code finalisé pour ce guide de démarrage rapide sur GitHub.

Prérequis

Avant de commencer, assurez-vous de :

• Créer un compte Azure avec un abonnement actif. Pour plus d’informations, consultez Créer un compte gratuitement

• Installez Python 3.7+.

• Créer une ressource Azure Communication Services. Pour plus d’informations, consultez Démarrage rapide : Créer et gérer des ressources Communication Services. Vous devez enregistrer le point de terminaison et la chaîne de connexion de votre ressource pour ce guide de démarrage rapide.

• Jeton d’accès utilisateur. Veillez à définir l’étendue sur chat (conversation) et prenez note de la chaîne du jeton et de la chaîne user_id. Vous pouvez également utiliser Azure CLI et exécuter la commande ci-dessous avec votre chaîne de connexion pour créer un utilisateur et un jeton d’accès.

  az communication identity token issue --scope chat --connection-string "yourConnectionString"
  

  Pour plus d’informations, consultez Utiliser Azure CLI pour créer et gérer des jetons d’accès.

Configuration

Créer une application Python

Ouvrez votre fenêtre de terminal ou de commande, créez un répertoire pour votre application, puis accédez-y.

mkdir chat-quickstart && cd chat-quickstart

Utilisez un éditeur de texte pour créer un fichier nommé start-chat.py dans le répertoire racine du projet. Ajoutez la structure du programme, y compris la gestion des exceptions de base. Dans les sections suivantes, vous ajouterez l’ensemble du code source de ce guide de démarrage rapide dans ce fichier.

import os
# Add required SDK components from quickstart here

try:
    print('Azure Communication Services - Chat Quickstart')
    # Quickstart code goes here
except Exception as ex:
    print('Exception:')
    print(ex)

Installer le kit SDK

Utilisez la commande suivante pour installer le kit SDK :

pip install azure-communication-chat

Modèle objet

Les classes et interfaces suivantes gèrent quelques-unes des principales fonctionnalités du kit de développement logiciel (SDK) Azure Communication Services Chat pour Python.

Créer un client de conversation

Pour créer un client de conversation, utilisez le point de terminaison Communication Services ainsi que le jeton d’accès que vous avez généré au cours des étapes prérequises.

pip install azure-communication-identity

from azure.communication.chat import ChatClient, CommunicationTokenCredential

endpoint = "<replace with your resource endpoint>"
chat_client = ChatClient(endpoint, CommunicationTokenCredential("<Access Token>"))

Ce guide de démarrage rapide ne couvre pas la création d’un niveau de service permettant de gérer les jetons de votre application de conversation, mais cette opération est recommandée. Pour plus d’informations, consultez la section « Architecture des conversations » de Concepts relatifs aux conversations.

Démarrer un fil de conversation

Utilisez la méthode create_chat_thread pour créer un fil de conversation.

• Utilisez topic pour attribuer un thème à ce fil de conversation. Vous pouvez mettre à jour ce thème après la création du fil de conversation à l’aide de la fonction update_thread.
• Utilisez thread_participants pour lister le ChatParticipant à ajouter au fil de conversation. Le ChatParticipant prend le type CommunicationUserIdentifier comme user.

CreateChatThreadResult est le résultat retourné par la création d’un fil de conversation. Vous pouvez l’utiliser pour extraire l’id du fil de conversation qui a été créé. Cet id peut ensuite être utilisé pour extraire un objet ChatThreadClient à l’aide de la méthode get_chat_thread_client. Vous pouvez utiliser ChatThreadClient pour effectuer d’autres opérations de conversation sur ce fil de conversation.

topic="test topic"

create_chat_thread_result = chat_client.create_chat_thread(topic)
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)

Obtenir un client de fil de conversation

La méthode get_chat_thread_client retourne un client de fil pour un fil qui existe déjà. Vous pouvez l’utiliser pour effectuer des opérations sur le fil de conversation créé. Par exemple, vous pouvez ajouter des participants et envoyer des messages. thread_id est l’ID unique du fil de conversation existant.

Vous pouvez utiliser ChatThreadClient pour effectuer d’autres opérations de conversation sur ce fil de conversation.

thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(thread_id)

Répertorier tous les fils de conversation

La méthode list_chat_threads retourne un itérateur de type ChatThreadItem.

• Utilisez start_time pour spécifier l’instant dans le passé le plus ancien auquel vous souhaitez accéder pour obtenir des fils de conversation.
• Utilisez results_per_page pour spécifier le nombre maximal de fils de conversation retournés par page.

Un itérateur égal à [ChatThreadItem] est la réponse retournée par l’énumération des fils de conversation.

from datetime import datetime, timedelta

start_time = datetime.utcnow() - timedelta(days=2)

chat_threads = chat_client.list_chat_threads(results_per_page=5, start_time=start_time)
for chat_thread_item_page in chat_threads.by_page():
    for chat_thread_item in chat_thread_item_page:
        print(chat_thread_item)
        print('Chat Thread Id: ', chat_thread_item.id)

Envoyer un message à un fil de conversation

Utilisez la méthode send_message pour envoyer un message à un fil de conversation que vous venez de créer, identifié par thread_id.

• Utilisez content pour fournir le contenu du message de conversation.
• Utilisez chat_message_type pour spécifier le type de contenu du message. Les valeurs possibles sont text et html. Si vous ne spécifiez aucune valeur, la valeur par défaut est text.
• Utilisez sender_display_name pour spécifier le nom d’affichage de l’expéditeur.
• Utilisez metadata (facultatif) pour inclure toutes les données supplémentaires que vous souhaitez envoyer avec le message. Ce champ constitue un mécanisme permettant aux développeurs d’étendre les fonctionnalités des messages de conversation et d’ajouter des informations personnalisées selon le cas d’usage. Par exemple, si vous partagez un lien de fichier dans le message, vous avez la possibilité d’ajouter « hasAttachment:true » dans les métadonnées pour que l’application du destinataire puisse l’analyser et l’afficher en conséquence.

SendChatMessageResult est la réponse retournée par l’envoi d’un message. Elle contient un ID, qui est l’ID unique du message.

from azure.communication.chat import ChatMessageType

topic = "test topic"
create_chat_thread_result = chat_client.create_chat_thread(topic)
thread_id = create_chat_thread_result.chat_thread.id
chat_thread_client = chat_client.get_chat_thread_client(create_chat_thread_result.chat_thread.id)


content='Please take a look at the attachment'
sender_display_name='sender name'
metadata={
    'hasAttachment': 'true',
    'attachmentUrl': 'https://contoso.com/files/attachment.docx'
}

# specify chat message type with pre-built enumerations
send_message_result_w_enum = chat_thread_client.send_message(content=content, sender_display_name=sender_display_name, chat_message_type=ChatMessageType.TEXT, metadata=metadata)
print("Message sent: id: ", send_message_result_w_enum.id)

Recevoir les messages de conversation d’un fil de conversation

Vous pouvez récupérer les messages de conversation en interrogeant la méthode list_messages selon des intervalles définis.

• Utilisez results_per_page pour spécifier le nombre maximal de messages retournés par page.
• Utilisez start_time pour spécifier l’instant dans le passé le plus ancien auquel vous souhaitez accéder pour obtenir des messages.

Un itérateur de [ChatMessage] est la réponse retournée par l’énumération des messages.

from datetime import datetime, timedelta

start_time = datetime.utcnow() - timedelta(days=1)

chat_messages = chat_thread_client.list_messages(results_per_page=1, start_time=start_time)
for chat_message_page in chat_messages.by_page():
    for chat_message in chat_message_page:
        print("ChatMessage: Id=", chat_message.id, "; Content=", chat_message.content.message)

list_messages retourne la version la plus récente du message, avec les modifications ou les suppressions dont le message a éventuellement fait l’objet via update_message et delete_message. Pour les messages supprimés, ChatMessage.deleted_on retourne une valeur datetime indiquant à quel moment ce message a été supprimé. Pour les messages modifiés, ChatMessage.edited_on retourne une valeur datetime indiquant à quel moment le message a été modifié. Vous pouvez accéder à l’heure initiale de création du message à l’aide de ChatMessage.created_on, qui peut être utilisée pour ordonner les messages.

list_messages retourne différents types de messages, qui peuvent être identifiés par ChatMessage.type.

Pour plus d’informations, consultez Types de message.

Envoyer une confirmation de lecture

Vous utilisez la méthode send_read_receipt pour publier un événement de confirmation de lecture sur un fil de conversation, pour le compte d’un utilisateur.

• Utilisez message_id pour spécifier l’identifiant du dernier message lu par l’utilisateur actuel.

content='hello world'

send_message_result = chat_thread_client.send_message(content)
chat_thread_client.send_read_receipt(message_id=send_message_result.id)

Ajouter un utilisateur comme participant au fil de conversation

Quand vous créez un fil de conversation, vous pouvez y ajouter des utilisateurs et en supprimer. En ajoutant des utilisateurs, vous leur octroyez l’accès permettant d’envoyer des messages au fil de conversation et d’ajouter ou de supprimer d’autres participants. Avant d’appeler la méthode add_participants, vérifiez que vous avez acquis un nouveau jeton d’accès et une identité pour cet utilisateur. L’utilisateur a besoin de ce jeton d’accès pour initialiser le client de conversation.

Vous pouvez ajouter un ou plusieurs utilisateurs au fil de conversation à l’aide de la méthode add_participants, à condition qu’un nouveau jeton d’accès et qu’une nouvelle identité soient disponibles pour tous les utilisateurs.

Un list(tuple(ChatParticipant, CommunicationError)) est retourné. Quand le participant est correctement ajouté, une liste vide est attendue. Si vous rencontrez une erreur en ajoutant un participant, la liste est remplie avec les participants n’ayant pas pu être ajoutés, ainsi que l’erreur rencontrée.

from azure.communication.identity import CommunicationIdentityClient
from azure.communication.chat import ChatParticipant
from datetime import datetime

# create 2 users
identity_client = CommunicationIdentityClient.from_connection_string('<connection_string>')
new_users = [identity_client.create_user() for i in range(2)]

# # conversely, you can also add an existing user to a chat thread; provided the user_id is known
# from azure.communication.identity import CommunicationUserIdentifier
#
# user_id = 'some user id'
# user_display_name = "Wilma Flinstone"
# new_user = CommunicationUserIdentifier(user_id)
# participant = ChatParticipant(
#     identifier=new_user,
#     display_name=user_display_name,
#     share_history_time=datetime.utcnow())

participants = []
for _user in new_users:
  chat_thread_participant = ChatParticipant(
    identifier=_user,
    display_name='Fred Flinstone',
    share_history_time=datetime.utcnow()
  ) 
  participants.append(chat_thread_participant) 

response = chat_thread_client.add_participants(participants)

def decide_to_retry(error, **kwargs):
    """
    Insert some custom logic to decide if retry is applicable based on error
    """
    return True

# verify if all users has been successfully added or not
# in case of partial failures, you can retry to add all the failed participants 
retry = [p for p, e in response if decide_to_retry(e)]
if retry:
    chat_thread_client.add_participants(retry)

Répertorier les participants d’un fil de conversation

De la même façon que vous ajoutez un participant, vous pouvez également répertorier les participants d’une conversation.

Utilisez list_participants pour récupérer les participants à la conversation. Les deux commandes suivantes sont facultatives :

• Utilisez results_per_page pour spécifier le nombre maximal de participants à retourner par page.
• Utilisez skip pour ignorer les participants jusqu’à une position spécifiée dans la réponse.

Un itérateur de [ChatParticipant] est la réponse retournée par l’énumération des participants.

chat_thread_participants = chat_thread_client.list_participants()
for chat_thread_participant_page in chat_thread_participants.by_page():
    for chat_thread_participant in chat_thread_participant_page:
        print("ChatParticipant: ", chat_thread_participant)

Exécuter le code

Exécutez l’application à partir de votre répertoire d’application avec la commande python.

python start-chat.py

Exemple de code

Vous trouverez le code finalisé pour ce guide de démarrage rapide sur GitHub.

Prérequis

• Compte Azure avec un abonnement actif. Créez un compte gratuitement.

• Java Development Kit (JDK) version 8 ou ultérieure.

• Apache Maven.

• Créer une ressource Azure Communication Services. Pour plus d’informations, consultez Créer des ressources Azure Communication Services. Vous devez enregistrer le point de terminaison et la chaîne de connexion de votre ressource pour ce guide de démarrage rapide

• Jeton d’accès utilisateur. Veillez à définir l’étendue sur chat (conversation) et prenez note de la chaîne du jeton et de la chaîne user_id. Vous pouvez également utiliser Azure CLI et exécuter la commande ci-dessous avec votre chaîne de connexion pour créer un utilisateur et un jeton d’accès.

  az communication identity token issue --scope chat --connection-string "yourConnectionString"
  

  Pour plus d’informations, consultez Utiliser Azure CLI pour créer et gérer des jetons d’accès.

Configuration

Créer une application Java

Ouvrez votre terminal ou votre fenêtre Commande, puis accédez au répertoire dans lequel vous souhaitez créer votre application Java. Exécutez la commande ci-dessous pour générer le projet Java à partir du modèle maven-archetype-quickstart.

mvn archetype:generate -DgroupId=com.communication.quickstart -DartifactId=communication-quickstart -DarchetypeArtifactId=maven-archetype-quickstart -DarchetypeVersion=1.4 -DinteractiveMode=false

Vous remarquerez que l’objectif « generate » a créé un répertoire portant le même nom que l’artifactId. Sous ce répertoire, src/main/java directory contient le code source du projet, le répertoire src/test/java contient la source de test et le fichier pom.xml est le modèle objet du projet, ou POM.

Mettez à jour le fichier POM de votre application pour utiliser Java 8 ou version ultérieure :

<properties>
    <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    <maven.compiler.source>1.8</maven.compiler.source>
    <maven.compiler.target>1.8</maven.compiler.target>
</properties>

Ajouter les références de package pour le kit de développement logiciel (SDK) Chat

Dans votre fichier POM, référencez le package azure-communication-chat avec les API de conversation (Chat) :

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-chat</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-chat for the latest version --></version>
</dependency>

Pour l’authentification, votre client doit référencer le package azure-communication-common :

<dependency>
    <groupId>com.azure</groupId>
    <artifactId>azure-communication-common</artifactId>
    <version><!-- Please refer to https://search.maven.org/artifact/com.azure/azure-communication-common for the latest version --></version>
</dependency>

Modèle objet

Les classes et interfaces suivantes gèrent quelques-unes des principales fonctionnalités du kit de développement logiciel (SDK) Azure Communication Services Chat pour Java.

Créer un client de conversation

Pour créer un client de conversation, vous allez utiliser le point de terminaison Communication Services ainsi que le jeton d’accès qui a été généré au cours des étapes prérequises. Les jetons d’accès utilisateur vous permettent de créer des applications clientes qui s’authentifient directement auprès d’Azure Communication Services. Une fois que vous avez généré ces jetons sur votre serveur, transmettez-les en retour à un appareil client. Vous devez utiliser la classe CommunicationTokenCredential du kit de développement logiciel (SDK) commun pour transmettre le jeton à votre client de conversation.

En savoir plus sur l’Architecture de conversation

Si vous devez ajouter des instructions d’importation, veillez à ajouter uniquement des importations des espaces de noms com.azure.communication.chat et com.azure.communication.chat.models, et non de l’espace de noms com.azure.communication.chat.implementation. Dans le fichier App.java qui a été généré via Maven, vous pouvez commencer avec le code suivant :

package com.communication.quickstart;

import com.azure.communication.chat.*;
import com.azure.communication.chat.models.*;
import com.azure.communication.common.*;
import com.azure.core.http.rest.PagedIterable;

import java.io.*;
import java.util.*;

public class App
{
    public static void main( String[] args ) throws IOException
    {
        System.out.println("Azure Communication Services - Chat Quickstart");

        // Your unique Azure Communication service endpoint
        String endpoint = "<replace with your resource endpoint>";

        // User access token fetched from your trusted service
        String userAccessToken = "<USER_ACCESS_TOKEN>";

        // Create a CommunicationTokenCredential with the given access token, which is only valid until the token is valid
        CommunicationTokenCredential userCredential = new CommunicationTokenCredential(userAccessToken);

        // Initialize the chat client
        final ChatClientBuilder builder = new ChatClientBuilder();
        builder.endpoint(endpoint)
            .credential(userCredential);
        ChatClient chatClient = builder.buildClient();
    }
}

Démarrer un fil de conversation

Utilisez la méthode createChatThread pour créer un fil de conversation. createChatThreadOptions est utilisé pour décrire la demande de fil.

• Utilisez le paramètre topic du constructeur pour attribuer un sujet à cette conversation ; le sujet peut être mis à jour après que le fil de conversation a été créé à l’aide de la fonction UpdateThread.
• Utilisez participants pour lister les participants au fil à ajouter à la conversation. ChatParticipant prend l’utilisateur que vous avez créé dans le démarrage rapide Jeton d’accès utilisateur.

CreateChatThreadResult correspond à la réponse renvoyée par la création d’un fil de conversation. Elle contient une méthode getChatThread() qui retourne l’objet ChatThread permettant d’obtenir le client de thread à partir duquel obtenir ChatThreadClient pour effectuer des opérations sur le thread créé : ajout de participants, envoi d’un message, etc. L’objet ChatThread contient également la méthode getId() qui récupère l’ID unique du thread.

CommunicationUserIdentifier identity1 = new CommunicationUserIdentifier("<USER_1_ID>");
CommunicationUserIdentifier identity2 = new CommunicationUserIdentifier("<USER_2_ID>");

ChatParticipant firstThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity1)
    .setDisplayName("Participant Display Name 1");

ChatParticipant secondThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity2)
    .setDisplayName("Participant Display Name 2");

CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions("Topic")
    .addParticipant(firstThreadParticipant)
    .addParticipant(secondThreadParticipant);

CreateChatThreadResult result = chatClient.createChatThread(createChatThreadOptions);
String chatThreadId = result.getChatThread().getId();

Répertorier les fils de conversation

Utilisez la méthode listChatThreads pour récupérer la liste des fils de conversation existants.

PagedIterable<ChatThreadItem> chatThreads = chatClient.listChatThreads();

chatThreads.forEach(chatThread -> {
    System.out.printf("ChatThread id is %s.\n", chatThread.getId());
});

Obtenir un client de fil de conversation

La méthode getChatThreadClient retourne un client de fil pour un fil qui existe déjà. Elle peut être utilisée pour effectuer des opérations sur le fil créé : ajout de participants, envoi d’un message, etc. chatThreadId est l’ID unique du fil de conversation existant.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Envoyer un message à un fil de conversation

Utilisez la méthode sendMessage pour envoyer un message au thread que vous avez créé, identifié par chatThreadId. sendChatMessageOptions est utilisé pour décrire la demande de message de conversation.

• Utilisez content pour fournir le contenu du message de conversation.
• Utilisez type pour spécifier le type de contenu du message de conversation, TEXTE ou HTML.
• Utilisez senderDisplayName pour spécifier le nom d’affichage de l’expéditeur.
• Utilisez metadata (facultatif) pour inclure toutes les données supplémentaires que vous souhaitez envoyer avec le message. Ce champ constitue un mécanisme permettant aux développeurs d’étendre les fonctionnalités des messages de conversation et d’ajouter des informations personnalisées selon le cas d’usage. Par exemple, si vous partagez un lien de fichier dans le message, vous pouvez ajouter hasAttachment:true dans les métadonnées pour que l’application du destinataire puisse l’analyser et l’afficher en conséquence.

La réponse sendChatMessageResult contient un id, qui est l’ID unique du message.

Map<String, String> metadata = new HashMap<String, String>();
metadata.put("hasAttachment", "true");
metadata.put("attachmentUrl", "https://contoso.com/files/attachment.docx");

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
    .setContent("Please take a look at the attachment")
    .setType(ChatMessageType.TEXT)
    .setSenderDisplayName("Sender Display Name")
    .setMetadata(metadata);

SendChatMessageResult sendChatMessageResult = chatThreadClient.sendMessage(sendChatMessageOptions);
String chatMessageId = sendChatMessageResult.getId();

Recevoir les messages de conversation d’un fil de conversation

Vous pouvez récupérer les messages de conversation en interrogeant la méthode listMessages sur le client de fil de conversation selon des intervalles définis.

chatThreadClient.listMessages().forEach(message -> {
    System.out.printf("Message id is %s.\n", message.getId());
});

listMessages retourne la version la plus récente du message, avec les modifications ou les suppressions dont le message a éventuellement fait l’objet via .editMessage() et .deleteMessage(). Pour les messages supprimés, chatMessage.getDeletedOn() retourne une valeur datetime indiquant à quel moment ce message a été supprimé. Pour les messages modifiés, chatMessage.getEditedOn() retourne une valeur datetime indiquant à quel moment ce message a été modifié. Il est possible d’accéder à l’heure initiale de création du message à l’aide de chatMessage.getCreatedOn() ; elle peut être utilisée à des fins de classement des messages.

Pour en savoir plus sur les types de messages, consultez Types de messages.

Envoyer une confirmation de lecture

Utilisez la méthode sendReadReceipt pour publier un événement de confirmation de lecture sur un fil de conversation, pour le compte d’un utilisateur. chatMessageId correspond à ID unique du message de conversation lu.

String chatMessageId = message.getId();
chatThreadClient.sendReadReceipt(chatMessageId);

Répertorier les participants à la conversation

Utilisez listParticipants pour récupérer une collection paginée contenant les participants du fil de conversation identifié par chatThreadId.

PagedIterable<ChatParticipant> chatParticipantsResponse = chatThreadClient.listParticipants();
chatParticipantsResponse.forEach(chatParticipant -> {
    System.out.printf("Participant id is %s.\n", ((CommunicationUserIdentifier) chatParticipant.getCommunicationIdentifier()).getId());
});

Ajouter un utilisateur comme participant au fil de conversation

Une fois qu’un fil de conversation est créé, vous pouvez y ajouter des utilisateurs et en supprimer. En ajoutant des utilisateurs, vous leur permettez d’envoyer des messages au fil de conversation et d’ajouter/supprimer d’autres participants. Vous devez commencer par obtenir un nouveau jeton d’accès et une identité pour cet utilisateur. Avant d’appeler la méthode addParticipants, vérifiez que vous avez acquis un nouveau jeton d’accès et une identité pour cet utilisateur. L’utilisateur aura besoin de ce jeton d’accès pour initialiser son client de conversation.

Utilisez la méthode addParticipants pour ajouter des participants au fil.

• communicationIdentifier, obligatoire. Il s’agit du CommunicationIdentifier que vous avez créé avec le CommunicationIdentityClient dans le guide de démarrage rapide Jeton d’accès utilisateur.
• displayName, facultatif, est le nom d’affichage pour le participant au fil.
• shareHistoryTime, facultatif, est le moment à partir duquel l’historique de conversation est partagé avec le participant. Pour partager l’historique depuis le début du fil de conversation, attribuez à cette propriété une date égale ou antérieure à la date de création du fil. Pour ne pas partager l’historique antérieur au moment où le participant a été ajouté, définissez-la sur l’heure actuelle. Pour partager un historique partiel, attribuez-lui la date de votre choix.

List<ChatParticipant> participants = new ArrayList<ChatParticipant>();

CommunicationUserIdentifier identity3 = new CommunicationUserIdentifier("<USER_3_ID>");
CommunicationUserIdentifier identity4 = new CommunicationUserIdentifier("<USER_4_ID>");

ChatParticipant thirdThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity3)
    .setDisplayName("Display Name 3");

ChatParticipant fourthThreadParticipant = new ChatParticipant()
    .setCommunicationIdentifier(identity4)
    .setDisplayName("Display Name 4");

participants.add(thirdThreadParticipant);
participants.add(fourthThreadParticipant);

chatThreadClient.addParticipants(participants);

Exécuter le code

Accédez au répertoire contenant le fichier pom.xml, puis compilez le projet à l’aide de la commande mvn suivante.

mvn compile

Ensuite, générez le package.

mvn package

Exécutez la commande mvn suivante pour exécuter l’application.

mvn exec:java -Dexec.mainClass="com.communication.quickstart.App" -Dexec.cleanupDaemonThreads=false

Exemple de code

Vous trouverez le code finalisé pour ce guide de démarrage rapide sur GitHub.

Prérequis

Avant de commencer, assurez-vous de :

• Créer un compte Azure avec un abonnement actif. Pour plus d’informations, consultez Créer un compte gratuitement.

• Installez Android Studio que nous allons utiliser afin de créer une application Android pour le démarrage rapide des l’installation dépendances.

• Créer une ressource Azure Communication Services. Pour plus d’informations, consultez Créer des ressources Azure Communication Services. Vous devez enregistrer le point de terminaison et la chaîne de connexion de votre ressource pour ce guide de démarrage rapide.

• Créez deux utilisateurs Azure Communication Services et émettez pour eux un Jeton d’accès utilisateur. Veillez à définir l’étendue sur chat (conversation) et prenez note de la chaîne du jeton et de la chaîne user_id. Dans ce démarrage rapide, nous allons créer un thread avec un participant initial, puis y ajouter un deuxième participant. Vous pouvez également utiliser Azure CLI et exécuter la commande ci-dessous avec votre chaîne de connexion pour créer un utilisateur et un jeton d’accès.

  az communication identity token issue --scope chat --connection-string "yourConnectionString"
  

  Pour plus d’informations, consultez Utiliser Azure CLI pour créer et gérer des jetons d’accès.

Configuration

Créer une application Android

1. Ouvrez Android Studio, puis sélectionnez Create a new project.
2. Dans la fenêtre suivante, sélectionnez Empty Activity en tant que modèle de projet.
3. Lors du choix des options, entrez ChatQuickstart comme nom du projet.
4. Cliquez sur Suivant, puis choisissez le répertoire où vous voulez créer le projet.

Installer les bibliothèques

Nous allons utiliser Gradle pour installer les dépendances nécessaires de Communication Services. À partir de la ligne de commande, accédez au répertoire racine du projet ChatQuickstart. Ouvrez le fichier build.gradle de l’application et ajoutez les dépendances suivantes à la cible ChatQuickstart :

implementation 'com.azure.android:azure-communication-common:' + $azureCommunicationCommonVersion
implementation 'com.azure.android:azure-communication-chat:' + $azureCommunicationChatVersion
implementation 'org.slf4j:slf4j-log4j12:1.7.29'

Pour obtenir les derniers numéros de version, consultez les pages https://search.maven.org/artifact/com.azure.android/azure-communication-common et https://search.maven.org/artifact/com.azure.android/azure-communication-chat.

Exclure les fichiers méta dans les options d’empaquetage dans build.gradle à la racine

android {
   ...
    packagingOptions {
        exclude 'META-INF/DEPENDENCIES'
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/license'
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/notice'
        exclude 'META-INF/ASL2.0'
        exclude("META-INF/*.md")
        exclude("META-INF/*.txt")
        exclude("META-INF/*.kotlin_module")
    }
}

(Alternative) Pour installer des bibliothèques via Maven

Pour importer la bibliothèque dans votre projet à l’aide du système de génération Maven, ajoutez-la à la section dependencies du fichier pom.xml de votre application, en spécifiant son ID d’artefact et la version que vous souhaitez utiliser :

<dependency>
  <groupId>com.azure.android</groupId>
  <artifactId>azure-communication-chat</artifactId>
  <version><!-- Please refer to https://search.maven.org/artifact/com.azure.android/azure-communication-chat for the latest version --></version>
</dependency>

Configurer Azure Function

Pour plus d’informations, consultez Intégration d’Azure Function. Nous vous recommandons vivement l’intégration avec Azure Function pour éviter d’avoir à coder en dur les paramètres d’application.

Configuration des constantes d’application

Créez une classe ApplicationConstants qui stocke toutes les constantes d’application :

public class ApplicationConstants {
    public static final String SDK_VERSION = "<your_version>";
    public final static String SDK_NAME = "azure-communication-com.azure.android.communication.chat";
    public final static String APPLICATION_ID = "Chat_Test_App";
    public final static String TAG = "[Chat Test App]";
    public static CommunicationTokenCredential COMMUNICATION_TOKEN_CREDENTIAL;
}

Configurer les espaces réservés

Ouvrez et modifiez le fichier MainActivity.java. Dans ce démarrage rapide, nous allons ajouter notre code à MainActivity, puis afficher la sortie dans la console. Ce guide ne couvre pas la création d’une interface utilisateur. En haut du fichier, importez les bibliothèques Azure Communication Common et Azure Communication Chat, ainsi que les autres bibliothèques système :

import com.azure.android.communication.chat.*;
import com.azure.android.communication.chat.models.*;
import com.azure.android.communication.common.*;

import android.os.Bundle;
import android.util.Log;
import android.widget.Toast;

import com.jakewharton.threetenabp.AndroidThreeTen;

import java.util.ArrayList;
import java.util.List;

Copiez le code suivant dans la classe MainActivity du fichier MainActivity.java :

    private ChatAsyncClient chatAsyncClient;

    private void log(String msg) {
        Log.i(TAG, msg);
        Toast.makeText(this, msg, Toast.LENGTH_LONG).show();
    }
    
   @Override
    protected void onStart() {
        super.onStart();
        try {
            AndroidThreeTen.init(this);

            // Initialize application parameters if one of the conditions in '### Initialize Application Parameters' are met.

            // <CREATE A CHAT CLIENT>

            // <CREATE A CHAT THREAD>

            // <CREATE A CHAT THREAD CLIENT>

            // <SEND A MESSAGE>
            
            // <RECEIVE CHAT MESSAGES>

            // <ADD A USER>

            // <LIST USERS>

            // <REMOVE A USER>
            
            // <<SEND A TYPING NOTIFICATION>>
            
            // <<SEND A READ RECEIPT>>
               
            // <<LIST READ RECEIPTS>>
        } catch (Exception e){
            System.out.println("Quickstart failed: " + e.getMessage());
        }
    }

Initialisation des paramètres d’application

ACS_ENDPOINT, FIRST_USER_ID et FIRST_USER_ACCESS_TOKEN sont retournés par l’appel de la fonction Azure. Pour plus d’informations, consultez Intégration d’Azure Function. Nous utilisons la réponse à l’appel de la fonction Azure pour initialiser la liste des paramètres :

• ACS_ENDPOINT : le point de terminaison de votre ressource Communication Services.
• FIRST_USER_ID et SECOND_USER_ID : des identifiants utilisateur Communication Services valides générés par votre ressource Communication Services.
• FIRST_USER_ACCESS_TOKEN : le jeton d’accès Communication Services de <FIRST_USER_ID>.

Voici le bloc de code correspondant à l’initialisation des paramètres d’application par un appel à Azure Function :

try {
        UserTokenClient userTokenClient = new UserTokenClient(AZURE_FUNCTION_URL);
        //First user context
        userTokenClient.getNewUserContext();
        ACS_ENDPOINT = userTokenClient.getACSEndpoint();
        FIRST_USER_ID = userTokenClient.getUserId();
        FIRST_USER_ACCESS_TOKEN = userTokenClient.getUserToken();
        COMMUNICATION_TOKEN_CREDENTIAL = new CommunicationTokenCredential(FIRST_USER_ACCESS_TOKEN);
        //Second user context
        userTokenClient.getNewUserContext();
        SECOND_USER_ID = userTokenClient.getUserId();
    } catch (Throwable throwable) {
        //Your handling code
        logger.logThrowableAsError(throwable);
    }

Créer un client de conversation

Remplacez le commentaire <CREATE A CHAT CLIENT> par le code suivant (placez les instructions d’importation en haut du fichier) :

import com.azure.android.core.http.policy.UserAgentPolicy;

chatAsyncClient = new ChatClientBuilder()
    .endpoint(endpoint)
    .credential(new CommunicationTokenCredential(firstUserAccessToken))
    .addPolicy(new UserAgentPolicy(APPLICATION_ID, SDK_NAME, sdkVersion))
    .buildAsyncClient();

Modèle objet

Les classes et interfaces suivantes gèrent quelques-unes des principales fonctionnalités du kit de développement logiciel (SDK) Azure Communication Services Chat pour JavaScript.

Démarrer un fil de conversation

Nous allons utiliser notre ChatAsyncClient pour créer un thread avec un utilisateur initial.

Remplacez le commentaire <CREATE A CHAT THREAD> par le code suivant :

// A list of ChatParticipant to start the thread with.
List<ChatParticipant> participants = new ArrayList<>();
// The display name for the thread participant.
String displayName = "initial participant";
participants.add(new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier(firstUserId))
    .setDisplayName(displayName));

// The topic for the thread.
final String topic = "General";
// Optional, set a repeat request ID.
final String repeatabilityRequestID = "";
// Options to pass to the create method.
CreateChatThreadOptions createChatThreadOptions = new CreateChatThreadOptions()
    .setTopic(topic)
    .setParticipants(participants)
    .setIdempotencyToken(repeatabilityRequestID);

CreateChatThreadResult createChatThreadResult =
    chatAsyncClient.createChatThread(createChatThreadOptions).get();
ChatThreadProperties chatThreadProperties = createChatThreadResult.getChatThreadProperties();
threadId = chatThreadProperties.getId();

Obtenir un client de fil de conversation

Maintenant que nous avons créé un thread de conversation, nous allons obtenir un ChatThreadAsyncClient pour effectuer des opérations dans le thread. Remplacez le commentaire <CREATE A CHAT THREAD CLIENT> par le code suivant :

ChatThreadAsyncClient chatThreadAsyncClient = new ChatThreadClientBuilder()
    .endpoint(endpoint)
    .credential(new CommunicationTokenCredential(firstUserAccessToken))
    .addPolicy(new UserAgentPolicy(APPLICATION_ID, SDK_NAME, sdkVersion))
    .chatThreadId(threadId)
    .buildAsyncClient();

Envoyer un message à un fil de conversation

Nous allons envoyer le message à ce thread maintenant.

Remplacez le commentaire <SEND A MESSAGE> par le code suivant :

// The chat message content, required.
final String content = "Please take a look at the attachment";

// The display name of the sender, if null (i.e. not specified), an empty name will be set.
final String senderDisplayName = "An important person";

// Use metadata optionally to include any additional data you want to send along with the message.
// This field provides a mechanism for developers to extend chat message functionality and add
// custom information for your use case. For example, when sharing a file link in the message, you
// might want to add 'hasAttachment:true' in metadata so that recipient's application can parse
// that and display accordingly.
final Map<String, String> metadata = new HashMap<String, String>();
metadata.put("hasAttachment", "true");
metadata.put("attachmentUrl", "https://contoso.com/files/attachment.docx");

SendChatMessageOptions chatMessageOptions = new SendChatMessageOptions()
    .setType(ChatMessageType.TEXT)
    .setContent(content)
    .setSenderDisplayName(senderDisplayName)
    .setMetadata(metadata);

// A string is the response returned from sending a message, it is an id, which is the unique ID
// of the message.
chatMessageId = chatThreadAsyncClient.sendMessage(chatMessageOptions).get().getId();

Recevoir les messages de conversation d’un fil de conversation

Notifications en temps réel

Avec la signalisation en temps réel, vous pouvez vous abonner aux nouveaux messages entrants et mettre à jour en conséquence les messages actuellement en mémoire. Azure Communication Services prend en charge une liste d’événements auxquels vous pouvez vous abonner.

Remplacez le commentaire <RECEIVE CHAT MESSAGES> par le code suivant (placez les instructions d’importation en haut du fichier) :

// Start real time notification
chatAsyncClient.startRealtimeNotifications(firstUserAccessToken, getApplicationContext());

// Register a listener for chatMessageReceived event
chatAsyncClient.addEventHandler(ChatEventType.CHAT_MESSAGE_RECEIVED, (ChatEvent payload) -> {
    ChatMessageReceivedEvent chatMessageReceivedEvent = (ChatMessageReceivedEvent) payload;
    // You code to handle chatMessageReceived event
    
});

implementation ("com.azure.android:azure-communication-chat:1.0.0") {
    exclude group: 'com.microsoft', module: 'trouter-client-android'
}
implementation 'com.azure.android:azure-communication-calling:1.0.0'

Notifications Push

Pour plus d’informations, consultez les notifications Push Android .

Ajouter un utilisateur comme participant au fil de conversation

Remplacez le commentaire <ADD A USER> par le code suivant :

// The display name for the thread participant.
String secondUserDisplayName = "a new participant";
ChatParticipant participant = new ChatParticipant()
    .setCommunicationIdentifier(new CommunicationUserIdentifier(secondUserId))
    .setDisplayName(secondUserDisplayName);
        
chatThreadAsyncClient.addParticipant(participant);

Lister les utilisateurs dans un fil de conversation

Remplacez le commentaire <LIST USERS> par le code suivant (placez les instructions d’importation en haut du fichier) :

import com.azure.android.core.rest.util.paging.PagedAsyncStream;
import com.azure.android.core.util.RequestContext;

// The maximum number of participants to be returned per page, optional.
int maxPageSize = 10;

// Skips participants up to a specified position in response.
int skip = 0;

// Options to pass to the list method.
ListParticipantsOptions listParticipantsOptions = new ListParticipantsOptions()
    .setMaxPageSize(maxPageSize)
    .setSkip(skip);

PagedAsyncStream<ChatParticipant> participantsPagedAsyncStream =
      chatThreadAsyncClient.listParticipants(listParticipantsOptions, RequestContext.NONE);

participantsPagedAsyncStream.forEach(chatParticipant -> {
    // You code to handle participant
});

Supprimer un utilisateur d’un fil de conversation

Nous allons supprimer le deuxième utilisateur du thread maintenant.

Remplacez le commentaire <REMOVE A USER> par le code suivant :

// Using the unique ID of the participant.
chatThreadAsyncClient.removeParticipant(new CommunicationUserIdentifier(secondUserId)).get();

Envoyer une notification de saisie

Remplacez le commentaire <SEND A TYPING NOTIFICATION> par le code suivant :

chatThreadAsyncClient.sendTypingNotification().get();

Envoyer une confirmation de lecture

Nous allons anvoyer une confirmation de lecture pour le message envoyé ci-dessus.

Remplacez le commentaire <SEND A READ RECEIPT> par le code suivant :

chatThreadAsyncClient.sendReadReceipt(chatMessageId).get();

Répertorier les confirmations de lecture

Remplacez le commentaire <READ RECEIPTS> par le code suivant :

// The maximum number of participants to be returned per page, optional.
maxPageSize = 10;
// Skips participants up to a specified position in response.
skip = 0;
// Options to pass to the list method.
ListReadReceiptOptions listReadReceiptOptions = new ListReadReceiptOptions()
    .setMaxPageSize(maxPageSize)
    .setSkip(skip);

PagedAsyncStream<ChatMessageReadReceipt> readReceiptsPagedAsyncStream =
      chatThreadAsyncClient.listReadReceipts(listReadReceiptOptions, RequestContext.NONE);

readReceiptsPagedAsyncStream.forEach(readReceipt -> {
    // You code to handle readReceipt
});

Exécuter le code

Dans Android Studio, cliquez sur le bouton Run (Exécuter) pour générer et exécuter le projet. Dans la console, vous pouvez voir la sortie du code et la sortie de l’enregistreur d’événements du ChatClient.

Exemple de code

Vous trouverez le code finalisé pour ce guide de démarrage rapide sur GitHub.

Prérequis

Avant de commencer, assurez-vous de :

• Créer un compte Azure avec un abonnement actif. Pour plus d’informations, consultez Créer un compte gratuitement.

• Installez Visual Studio

• Créer une ressource Azure Communication Services. Pour plus d’informations, consultez Créer des ressources Azure Communication Services. Vous devez enregistrer le point de terminaison et la chaîne de connexion de votre ressource pour ce guide de démarrage rapide

• Jeton d’accès utilisateur. Veillez à définir l’étendue sur chat (conversation) et prenez note de la chaîne du jeton et de la chaîne user_id. Vous pouvez également utiliser Azure CLI et exécuter la commande ci-dessous avec votre chaîne de connexion pour créer un utilisateur et un jeton d’accès.

  az communication identity token issue --scope chat --connection-string "yourConnectionString"
  

  Pour plus d’informations, consultez Utiliser Azure CLI pour créer et gérer des jetons d’accès.

Configuration

Créer une application C#

Dans une fenêtre de console (par exemple cmd, PowerShell ou Bash), utilisez la commande dotnet new pour créer une application console avec le nom ChatQuickstart. Cette commande crée un projet C# « Hello World » simple avec un seul fichier source : Program.cs.

dotnet new console -o ChatQuickstart

Remplacez votre répertoire par le dossier d’application que vous venez de créer, puis utilisez la commande dotnet build pour compiler votre application.

cd ChatQuickstart
dotnet build

Installer le package

Installer le kit de développement logiciel (SDK) Azure Communication Chat pour .NET

dotnet add package Azure.Communication.Chat

Modèle objet

Les classes suivantes gèrent quelques-unes des principales fonctionnalités du kit de développement logiciel (SDK) Azure Communication Services Chat pour C#.

Créer un client de conversation

Pour créer un client de conversation, vous allez utiliser votre point de terminaison Communication Services ainsi que le jeton d’accès qui a été généré au cours des étapes prérequises. Vous devez utiliser la classe CommunicationIdentityClient du kit de développement logiciel (SDK) Identity pour créer un utilisateur et émettre un jeton à transmettre à votre client de conversation.

Apprenez-en davantage sur les jetons d’accès utilisateur.

Ce guide de démarrage rapide ne couvre pas la création d’un niveau de service pour gérer les jetons de votre application de conversation, bien que ceci soit recommandé. En savoir plus sur l’Architecture de conversation

Copiez les extraits de code suivants et collez-les dans le fichier source : Program.cs

using Azure;
using Azure.Communication;
using Azure.Communication.Chat;
using System;

namespace ChatQuickstart
{
    class Program
    {
        static async System.Threading.Tasks.Task Main(string[] args)
        {
            // Your unique Azure Communication service endpoint
            Uri endpoint = new Uri("<replace with your resource endpoint>");

            CommunicationTokenCredential communicationTokenCredential = new CommunicationTokenCredential(<Access_Token>);
            ChatClient chatClient = new ChatClient(endpoint, communicationTokenCredential);
        }
    }
}

Démarrer un fil de conversation

Utilisez la méthode createChatThread sur chatClient pour créer un fil de conversation

• Utilisez topic pour attribuer un sujet à cette conversation ; le sujet peut être mis à jour après que le fil de conversation a été créé à l’aide de la fonction UpdateTopic.
• Utilisez la propriété participants pour transmettre la liste d’objets ChatParticipant à ajouter au fil de conversation. L’objet ChatParticipant est initialisé avec un objet CommunicationIdentifier. CommunicationIdentifier peut être de type CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier ou PhoneNumberIdentifier. Par exemple, pour obtenir un objet CommunicationIdentifier, vous devez passer un ID d’accès que vous avez créé en suivant les instructions fournies dans Créer un utilisateur

L’objet de réponse de la méthode createChatThread contient les détails de chatThread. Pour interagir avec les opérations du fil de conversation, telles que l’ajout de participants, l’envoi d’un message, la suppression d’un message, etc., une instance de client chatThreadClient doit être instanciée à l’aide de la méthode GetChatThreadClient sur le client ChatClient.

var chatParticipant = new ChatParticipant(identifier: new CommunicationUserIdentifier(id: "<Access_ID>"))
{
    DisplayName = "UserDisplayName"
};
CreateChatThreadResult createChatThreadResult = await chatClient.CreateChatThreadAsync(topic: "Hello world!", participants: new[] { chatParticipant });
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: createChatThreadResult.ChatThread.Id);
string threadId = chatThreadClient.Id;

Obtenir un client de fil de conversation

La méthode GetChatThreadClient retourne un client de fil pour un fil qui existe déjà. Il peut être utilisé dans les opérations effectuées sur le fil créé : ajout de membres, envoi d’un message, etc. threadId est l’ID unique du fil de conversation existant.

string threadId = "<THREAD_ID>";
ChatThreadClient chatThreadClient = chatClient.GetChatThreadClient(threadId: threadId);

Répertorier tous les fils de conversation

Utilisez GetChatThreads pour récupérer tous les fils de conversation dont fait partie l’utilisateur.

AsyncPageable<ChatThreadItem> chatThreadItems = chatClient.GetChatThreadsAsync();
await foreach (ChatThreadItem chatThreadItem in chatThreadItems)
{
    Console.WriteLine($"{ chatThreadItem.Id}");
}

Envoyer un message à un fil de conversation

Utilisez SendMessage pour envoyer un message à un fil de conversation.

• Utilisez content pour fournir le contenu du message, ce qui est obligatoire.
• Utilisez type pour le type de contenu du message tel que « Text » ou « Html ». S’il n’est pas spécifié, « Text » est défini.
• Utilisez senderDisplayName pour spécifier le nom d’affichage de l’expéditeur. S’il n’est pas spécifié, une chaîne vide est définie.
• Utilisez metadata (facultatif) pour inclure toutes les données supplémentaires que vous souhaitez envoyer avec le message. Ce champ constitue un mécanisme permettant aux développeurs d’étendre les fonctionnalités des messages de conversation et d’ajouter des informations personnalisées selon le cas d’usage. Par exemple, lors du partage d’un lien de fichier dans le message, vous souhaiterez peut-être ajouter « hasAttachment:true » dans les métadonnées pour que l’application du destinataire puisse l’analyser et l’afficher en conséquence.

SendChatMessageOptions sendChatMessageOptions = new SendChatMessageOptions()
{
    Content = "Please take a look at the attachment",
    MessageType = ChatMessageType.Text
};
sendChatMessageOptions.Metadata["hasAttachment"] = "true";
sendChatMessageOptions.Metadata["attachmentUrl"] = "https://contoso.com/files/attachment.docx";

SendChatMessageResult sendChatMessageResult = await chatThreadClient.SendMessageAsync(sendChatMessageOptions);

string messageId = sendChatMessageResult.Id;

Recevoir les messages de conversation d’un fil de conversation

Vous pouvez récupérer les messages de conversation en interrogeant la méthode GetMessages sur le client de fil de conversation selon des intervalles définis.

AsyncPageable<ChatMessage> allMessages = chatThreadClient.GetMessagesAsync();
await foreach (ChatMessage message in allMessages)
{
    Console.WriteLine($"{message.Id}:{message.Content.Message}");
}

GetMessages accepte un paramètre DateTimeOffset facultatif. Si ce décalage est spécifié, vous recevez les messages qui ont été reçus, mis à jour ou supprimés après celui-ci. Notez que les messages reçus avant la période de décalage, mais qui ont été modifiés ou supprimés après ladite période sont également retournés.

GetMessages retourne la version la plus récente du message, avec les modifications ou les suppressions dont le message a éventuellement fait l’objet via UpdateMessage et DeleteMessage. Pour les messages supprimés, chatMessage.DeletedOn retourne une valeur datetime indiquant à quel moment ce message a été supprimé. Pour les messages modifiés, chatMessage.EditedOn retourne une valeur datetime indiquant à quel moment ce message a été modifié. Il est possible d’accéder à l’heure initiale de création du message à l’aide de chatMessage.CreatedOn ; elle peut être utilisée à des fins de classement des messages.

GetMessages retourne différents types de messages qui peuvent être identifiés par chatMessage.Type. Ces types sont les suivants :

• Text: Message de conversation ordinaire envoyé par un membre du fil.

• Html : Message en texte mis en forme. Notez que les utilisateurs Communication Services ne peuvent actuellement pas envoyer de messages en texte enrichi. Ce type de message est pris en charge par les messages qu’envoient les utilisateurs Teams aux utilisateurs Communication Services dans les scénarios d’interopérabilité de Teams.

• TopicUpdated: Message système qui indique que le sujet a été mis à jour. (lecture seule)

• ParticipantAdded : message système qui indique qu’un ou plusieurs participants ont été ajoutés au fil de conversation. (lecture seule)

• ParticipantRemoved : Message système qui indique qu’un participant a été supprimé du fil de conversation.

Pour plus d’informations, consultez Types de messages.

Ajouter un utilisateur comme participant au fil de conversation

Une fois qu’un fil est créé, vous pouvez y ajouter des utilisateurs ou en supprimer. En ajoutant des utilisateurs, vous leur permettez d’envoyer des messages au fil de conversation et d’ajouter ou de supprimer d’autres participants. Avant d’appeler AddParticipants, vérifiez que vous avez acquis un nouveau jeton d’accès et une identité pour cet utilisateur. L’utilisateur aura besoin de ce jeton d’accès pour initialiser son client de conversation.

Utilisez AddParticipants pour ajouter un ou plusieurs participants au fil de conversation. Voici les attributs pris en charge pour chaque participant au fil de conversation :

• communicationUser, obligatoire. Il s’agit de l’identité du participant au fil de conversation.
• displayName, facultatif, est le nom d’affichage pour le participant au fil.
• shareHistoryTime, facultatif. Il s’agit du moment à partir duquel l’historique de conversation est partagé avec le participant.

var josh = new CommunicationUserIdentifier(id: "<Access_ID_For_Josh>");
var gloria = new CommunicationUserIdentifier(id: "<Access_ID_For_Gloria>");
var amy = new CommunicationUserIdentifier(id: "<Access_ID_For_Amy>");

var participants = new[]
{
    new ChatParticipant(josh) { DisplayName = "Josh" },
    new ChatParticipant(gloria) { DisplayName = "Gloria" },
    new ChatParticipant(amy) { DisplayName = "Amy" }
};

await chatThreadClient.AddParticipantsAsync(participants: participants);

Obtenir les participants au fil de conversation

Utilisez GetParticipants pour récupérer les participants au fil de conversation.

AsyncPageable<ChatParticipant> allParticipants = chatThreadClient.GetParticipantsAsync();
await foreach (ChatParticipant participant in allParticipants)
{
    Console.WriteLine($"{((CommunicationUserIdentifier)participant.User).Id}:{participant.DisplayName}:{participant.ShareHistoryTime}");
}

Envoyer une confirmation de lecture

Utilisez SendReadReceipt pour informer les autres participants que le message est lu par l’utilisateur.

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

Exécuter le code

Exécutez l’application à partir de votre répertoire d’application avec la commande dotnet run.

dotnet run

Exemple de code

Vous trouverez le code finalisé pour ce guide de démarrage rapide sur GitHub.

Prérequis

Avant de commencer, assurez-vous de :

• Créer un compte Azure avec un abonnement actif. Pour plus d’informations, consultez Créer un compte gratuitement

• Installez Xcode et CocoaPods. Vous utilisez Xcode pour créer une application iOS servant au guide de démarrage rapide, et CocoaPods pour installer les dépendances.

• Créer une ressource Azure Communication Services. Pour plus d’informations, consultez Démarrage rapide : Créer et gérer des ressources Communication Services. Vous devez enregistrer le point de terminaison et la chaîne de connexion de votre ressource pour ce guide de démarrage rapide.

• Créez deux utilisateurs dans Azure Communication Services, et émettez pour eux un jeton d’accès utilisateur. Veillez à définir l’étendue sur chat (conversation) et prenez note de la chaîne du jeton et de la chaîne user_id. Dans ce guide de démarrage rapide, vous créez un fil de conversation avec un participant initial, puis vous y ajoutez un deuxième participant. Vous pouvez également utiliser Azure CLI et exécuter la commande ci-dessous avec votre chaîne de connexion pour créer un utilisateur et un jeton d’accès.

  az communication identity token issue --scope chat --connection-string "yourConnectionString"
  

  Pour plus d’informations, consultez Utiliser Azure CLI pour créer et gérer des jetons d’accès.

Configuration

Créer une application iOS

Ouvrez Xcode et sélectionnez Create a new Xcode project (Créer un projet Xcode). Sélectionnez ensuite iOS comme plateforme, et Application pour le modèle.

En guise de nom de projet, entrez ChatQuickstart. Sélectionnez ensuite Storyboard comme interface, UIKit App Delegate comme cycle de vie et SWIFT comme langage.

Sélectionnez Suivant, puis choisissez le répertoire où vous voulez créer le projet.

Installer les bibliothèques

Utilisez CocoaPods pour installer les dépendances nécessaires de Communication Services.

À partir de la ligne de commande, accédez au répertoire racine du projet iOS ChatQuickstart. Créez un Podfile avec le contenu suivant : pod init.

Ouvrez le Podfile et ajoutez les dépendances suivantes à la cible ChatQuickstart :

pod 'AzureCommunicationChat', '~> 1.3.6'

Installez les dépendances à l’aide de la commande suivante : pod install. Notez que cette opération crée également un espace de travail Xcode.

Après l’exécution de pod install, rouvrez le projet dans Xcode en sélectionnant le nouveau .xcworkspace.

Configurer les espaces réservés

Ouvrez l’espace de travail ChatQuickstart.xcworkspace dans Xcode, puis ouvrez ViewController.swift.

Dans ce guide de démarrage rapide, vous ajoutez votre code à viewController et affichez la sortie dans la console Xcode. Ce guide de démarrage rapide ne traite pas de la création d’une interface utilisateur dans iOS.

En haut de viewController.swift, importez les bibliothèques AzureCommunication et AzureCommunicatonChat :

import AzureCommunicationCommon
import AzureCommunicationChat

Copiez le code suivant dans la méthode viewDidLoad() de ViewController :

override func viewDidLoad() {
        super.viewDidLoad()
        // Do any additional setup after loading the view.

        let semaphore = DispatchSemaphore(value: 0)
        DispatchQueue.global(qos: .background).async {
            do {
                // <CREATE A CHAT CLIENT>
                
                // <CREATE A CHAT THREAD>

                // <LIST ALL CHAT THREADS>

                // <GET A CHAT THREAD CLIENT>

                // <SEND A MESSAGE>

                // <SEND A READ RECEIPT >

                // <RECEIVE MESSAGES>

                // <ADD A USER>
                
                // <LIST USERS>
            } catch {
                print("Quickstart failed: \(error.localizedDescription)")
            }
        }
    }

À des fins de démonstration, nous allons utiliser un sémaphore pour synchroniser votre code. Dans les étapes suivantes, vous remplacez les espaces réservés par un exemple de code en utilisant la bibliothèque Conversation Azure Communication Services.

Créer un client de conversation

Pour créer un client de conversation, vous allez utiliser votre point de terminaison Communication Services ainsi que le jeton d’accès qui a été généré au cours des étapes prérequises.

Apprenez-en davantage sur les jetons d’accès utilisateur.

Ce guide de démarrage rapide ne couvre pas la création d’un niveau de service pour gérer les jetons de votre application de conversation, bien que ceci soit recommandé. En savoir plus sur l’Architecture de conversation

Remplacez le commentaire <CREATE A CHAT CLIENT> par l’extrait de code suivant :

let endpoint = "<ACS_RESOURCE_ENDPOINT>"
let credential =
try CommunicationTokenCredential(
    token: "<ACCESS_TOKEN>"
)
let options = AzureCommunicationChatClientOptions()

let chatClient = try ChatClient(
    endpoint: endpoint,
    credential: credential,
    withOptions: options
)

Remplacez <ACS_RESOURCE_ENDPOINT> par le point de terminaison de votre ressource Azure Communication Services. Remplacez <ACCESS_TOKEN> par un jeton d’accès Communication Services valide.

Modèle objet

Les classes et interfaces suivantes gèrent quelques-unes des principales fonctionnalités du kit SDK Azure Communication Services Chat pour iOS.

Démarrer un fil de conversation

CreateChatThreadResult correspond à la réponse renvoyée par la création d’un fil de conversation. Il contient une propriété chatThread qui correspond à l’objet ChatThreadProperties. Cet objet contient la propriété threadId qui permet d’obtenir un ChatThreadClient pour effectuer des opérations sur le thread créé : ajouter des participants, envoyer un message, etc.

Remplacez le commentaire <CREATE A CHAT THREAD> par l’extrait de code suivant :

let request = CreateChatThreadRequest(
    topic: "Quickstart",
    participants: [
        ChatParticipant(
            id: CommunicationUserIdentifier("<USER_ID>"),
            displayName: "Jack"
        )
    ]
)

var threadId: String?
chatClient.create(thread: request) { result, _ in
    switch result {
    case let .success(result):
        threadId = result.chatThread?.id

    case .failure:
        fatalError("Failed to create thread.")
    }
    semaphore.signal()
}
semaphore.wait()

Remplacez <USER_ID> par un ID d’utilisateur Communication Services valide.

Vous utilisez ici un sémaphore pour attendre le gestionnaire d’achèvement avant de continuer. Dans les étapes ultérieures, vous utiliserez le threadId de la réponse retournée au gestionnaire d’achèvement.

Répertorier tous les fils de conversation

Après la création d’un fil de conversation, nous pouvons lister tous les fils de conversation en appelant la méthode listChatThreads sur ChatClient. Remplacez le commentaire <LIST ALL CHAT THREADS> par le code suivant :

chatClient.listThreads { result, _ in
    switch result {
    case let .success(threads):
        guard let chatThreadItems = threads.pageItems else {
            print("No threads returned.")
            return
        }

        for chatThreadItem in chatThreadItems {
            print("Thread id: \(chatThreadItem.id)")
        }
    case .failure:
        print("Failed to list threads")
    }
    semaphore.signal()
}
semaphore.wait()

Obtenir un client de fil de conversation

La méthode createClient retourne un ChatThreadClient pour un fil qui existe déjà. Elle peut être utilisée pour effectuer des opérations sur le fil créé : ajout de participants, envoi d’un message, etc. threadId est l’ID unique du fil de conversation existant.

Remplacez le commentaire <GET A CHAT THREAD CLIENT> par le code suivant :

let chatThreadClient = try chatClient.createClient(forThread: threadId!)

Envoyer un message à un fil de conversation

Utilisez la méthode send pour envoyer un message à un thread identifié par threadId.

SendChatMessageRequest est utilisé pour décrire la demande de message :

• Utiliser content pour fournir le contenu du message de conversation
• Utiliser senderDisplayName pour spécifier le nom d’affichage de l’expéditeur
• Utiliser type pour spécifier le type de message, par exemple « text » ou « html »
• Utilisez metadata (facultatif) pour inclure toutes les données supplémentaires que vous souhaitez envoyer avec le message. Ce champ constitue un mécanisme permettant aux développeurs d’étendre les fonctionnalités des messages de conversation et d’ajouter des informations personnalisées selon le cas d’usage. Par exemple, lors du partage d’un lien de fichier dans le message, vous souhaiterez peut-être ajouter « hasAttachment:true » dans les métadonnées pour que l’application du destinataire puisse l’analyser et l’afficher en conséquence.

SendChatMessageResult est la réponse retournée à la suite de l’envoi du message; elle contient un ID, qui est l’ID unique du message.

Remplacez le commentaire <SEND A MESSAGE> par l’extrait de code suivant :

let message = SendChatMessageRequest(
                        content: "Hello!",
                        senderDisplayName: "Jack",
                        type: .text,
                        metadata: [
                            "hasAttachment": "true",
                            "attachmentUrl": "https://contoso.com/files/attachment.docx"
                        ]
                    )

var messageId: String?

chatThreadClient.send(message: message) { result, _ in
    switch result {
    case let .success(result):
        print("Message sent, message id: \(result.id)")
        messageId = result.id
    case .failure:
        print("Failed to send message")
    }
    semaphore.signal()
}
semaphore.wait()

Envoyer une confirmation de lecture

Utilisez la méthode sendReadReceipt pour publier un événement de confirmation de lecture sur un fil de conversation, pour le compte d’un utilisateur. messageId correspond à ID unique du message de conversation lu.

Remplacez le commentaire <SEND A READ RECEIPT> par le code suivant :

if let id = messageId {
    chatThreadClient.sendReadReceipt(forMessage: id) { result, _ in
        switch result {
        case .success:
            print("Read receipt sent")
        case .failure:
            print("Failed to send read receipt")
        }
        semaphore.signal()
    }
    semaphore.wait()
} else {
    print("Cannot send read receipt without a message id")
}

Recevoir les messages de conversation d’un fil de conversation

Avec la signalisation en temps réel, vous pouvez vous abonner pour écouter les nouveaux messages entrants et mettre à jour en conséquence les messages actuellement en mémoire. Azure Communication Services prend en charge une liste d’événements auxquels vous pouvez vous abonner.

Remplacez le commentaire <RECEIVE MESSAGES> par le code suivant. Après avoir activé les notifications, essayez d’envoyer de nouveaux messages pour voir les ChatMessageReceivedEvents.

chatClient.startRealTimeNotifications { result in
    switch result {
    case .success:
        print("Real-time notifications started.")
    case .failure:
        print("Failed to start real-time notifications.")
    }
    semaphore.signal()
}
semaphore.wait()

chatClient.register(event: .chatMessageReceived, handler: { response in
    switch response {
    case let .chatMessageReceivedEvent(event):
        print("Received a message: \(event.message)")
    default:
        return
    }
})

Vous pouvez aussi récupérer les messages de conversation en interrogeant la méthode listMessages selon des intervalles définis. Regarder l’extrait de code suivant pour listMessages

chatThreadClient.listMessages { result, _ in
    switch result {
    case let .success(messagesResult):
        guard let messages = messagesResult.pageItems else {
            print("No messages returned.")
            return
        }

        for message in messages {
            print("Received message with id: \(message.id)")
        }

    case .failure:
        print("Failed to receive messages")
    }
    semaphore.signal()
}
semaphore.wait()

Ajouter un utilisateur comme participant au fil de conversation

Une fois qu’un fil est créé, vous pouvez y ajouter des utilisateurs ou en supprimer. En ajoutant des utilisateurs, vous leur permettez d’envoyer des messages au fil de conversation et d’ajouter ou de supprimer d’autres participants. Avant d’appeler add, vérifiez que vous avez acquis un nouveau jeton d’accès et une identité pour cet utilisateur. L’utilisateur aura besoin de ce jeton d’accès pour initialiser son client de conversation.

Utilisez la méthode add de ChatThreadClient pour ajouter un ou plusieurs participants au thread de conversation. Voici les attributs pris en charge pour chaque participant au fil de conversation :

• id, obligatoire. Il s’agit de l’identité du participant au fil de conversation.
• displayName, facultatif, est le nom d’affichage pour le participant au fil.
• shareHistoryTime, facultatif. Il s’agit du moment à partir duquel l’historique de conversation est partagé avec le participant.

Remplacez le commentaire <ADD A USER> par le code suivant :

let user = ChatParticipant(
    id: CommunicationUserIdentifier("<USER_ID>"),
    displayName: "Jane"
)

chatThreadClient.add(participants: [user]) { result, _ in
    switch result {
    case let .success(result):
        if let errors = result.invalidParticipants, !errors.isEmpty {
            print("Error adding participant")
        } else {
            print("Added participant")
        }
    case .failure:
        print("Failed to add the participant")
    }
    semaphore.signal()
}
semaphore.wait()

Remplacez <USER_ID> par l’ID d’utilisateur Communication Services de l’utilisateur à ajouter.

Lister les utilisateurs dans un fil de conversation

Utilisez la méthode listParticipants pour obtenir tous les participants d’un thread de conversation particulier.

Remplacez le commentaire <LIST USERS> par le code suivant :

chatThreadClient.listParticipants { result, _ in
    switch result {
    case let .success(participantsResult):
        guard let participants = participantsResult.pageItems else {
            print("No participants returned.")
            return
        }

        for participant in participants {
            let user = participant.id as! CommunicationUserIdentifier
            print("User with id: \(user.identifier)")
        }
    case .failure:
        print("Failed to list participants")
    }
    semaphore.signal()
}
semaphore.wait()

Notifications Push

Les notifications push alertent les clients des messages entrants dans un fil de discussion dans les situations où l'application mobile ne s'exécute pas au premier plan. Actuellement, l’envoi de notifications Push de conversation avec le hub de notification est pris en charge pour les SDK IOS dans la version 1.3.0. Pour plus d’informations, reportez-vous à l’article Activer la notification Push dans votre application de conversation.

Exécuter le code

Dans Xcode, cliquez sur le bouton Run (Exécuter) pour générer et exécuter le projet. Dans la console, vous pouvez voir la sortie du code et la sortie de l’enregistreur d’événements du ChatClient.

Remarque : Définissez Build Settings > Build Options > Enable Bitcode sur No. Actuellement, le kit SDK AzureCommunicationChat pour iOS ne prend pas en charge l’activation du Bitcode. Le problème suivant est suivi sur GitHub.

Exemple de code

Vous trouverez le code finalisé pour ce guide de démarrage rapide sur GitHub.

Prérequis

• Un compte Azure avec un abonnement actif ou créez gratuitement un compte Azure.

• Une ressource Azure Communication Services active ou créez une ressource Communication Services.

• Une ressource Azure Logic Apps active, ou créez une application logique vide avec le déclencheur que vous souhaitez utiliser. Comme le connecteur Communication Services Chat ne fournit que des actions actuellement, votre application logique nécessite au minimum un déclencheur.

Créer un utilisateur

Effectuez ces étapes dans Power Automate avec votre flux Power Automate ouvert en mode d’édition.

Pour ajouter une nouvelle étape dans votre workflow à l’aide du connecteur Communication Services Identity :

1. Dans le concepteur, sous l’étape à laquelle vous voulez ajouter la nouvelle action, choisissez Nouvelle étape. Vous pouvez également ajouter la nouvelle action entre des étapes, déplacez votre pointeur sur la flèche située entre ces étapes, sélectionnez le signe plus (+), puis sélectionnez Ajouter une action.

2. Dans la zone de recherche Choisir une opération, entrez Communication Services Identity. Dans la liste de la liste d’actions, sélectionnez Créer un utilisateur.

   

3. Entrez la chaîne de connexion. Pour obtenir l’URL de chaîne de connexion dans le Portail Azure, accédez à la ressource Azure Communication Services. Dans le menu des ressources, sélectionnez Clés, puis Chaîne de connexion. Sélectionnez l’icône Copier pour effectuer la copie de la chaîne de connexion.

   

4. Attribuez un nom à cette connexion.

5. Sélectionnez Afficher les options avancées, puis sélectionnez l’étendue du jeton. L’action génère un jeton d’accès et son heure d’expiration avec spécification de l’étendue. Cette action génère également un identifiant utilisateur qui est une identité d’utilisateur de Communication Services.

   

6. Dans Élément des étendues de jeton, sélectionnez Conversation.

   

7. Cliquez sur Créer. L’identifiant utilisateur et un jeton d’accès s’affichent.

Créer un fil de conversation

1. Ajoutez une nouvelle action.

2. Dans la zone de recherche Choisir une opération, entrez Communication Services Chat. Dans la liste d’actions, sélectionnez Créer un thread de conversation.

   

3. Entrez l’URL du point de terminaison Communication Services. Pour obtenir l’URL du point de terminaison dans le Portail Azure, accédez à la ressource Communication Services. Dans le menu de la ressource, sélectionnez Clés, puis Point de terminaison.

4. Attribuez un nom à cette connexion.

5. Sélectionnez le jeton d’accès qui a été généré dans la section précédente, puis ajoutez une description à la rubrique du fil de conversation. Ajoutez l’utilisateur créé et entrez un nom pour le participant.

   

Envoyer un message

1. Ajoutez une nouvelle action.

2. Dans la zone de recherche Choisir une opération, entrez Communication Services Chat. Dans la liste d’actions, sélectionnez Envoyer un message au thread de conversation.

   

3. Entrez le jeton d’accès, l’ID de thread, le contenu et le nom.

   

Répertorier les messages de thread de conversation

Pour vérifier que vous avez correctement envoyé un message :

1. Ajoutez une nouvelle action.

2. Dans la zone de recherche Choisir une opération, entrez Communication Services Chat. Dans la liste d’actions, sélectionnez Liste des messages de thread de conversation.

   

3. Entrez le jeton d’accès et l’ID de thread.

   

Tester votre application logique

Pour lancer manuellement votre workflow, sélectionnez Exécuter dans la barre d’outils du concepteur. Le workflow crée un utilisateur, émet un jeton d’accès pour cet utilisateur, puis supprime le jeton et supprime l’utilisateur. Pour en savoir plus, consultez Exécuter votre workflow.

À présent, sélectionnez Répertorier les messages de thread de conversation. Dans les sorties d’action, recherchez le message qui a été envoyé.

Nettoyer des ressources de flux de travail

Pour nettoyer le workflow de votre application logique et les ressources associées, consultez les instructions permettant de nettoyer des ressources Logic Apps.