Azure Communication Chat-Clientbibliothek für JavaScript – Version 1.5.2
Mit Azure Communication Services für Chat können Entwickler ihrer App Chatfunktionen hinzufügen. Verwenden Sie diese Clientbibliothek, um Chatthreads und ihre Benutzer zu verwalten und Chatnachrichten zu senden und zu empfangen.
Weitere Informationen zu Azure Communication Services hier
Erste Schritte
Voraussetzungen
- Ein Azure-Abonnement.
- Eine vorhandene Kommunikationsdiensteressource. Wenn Sie die Ressource erstellen müssen, können Sie das Azure Portal, die Azure PowerShell-oder die Azure CLI-verwenden.
- Node.js
Installation
npm install @azure/communication-chat
Browserunterstützung
JavaScript-Bündel
Um diese Clientbibliothek im Browser zu verwenden, müssen Sie zuerst einen Bundler verwenden. Ausführliche Informationen dazu finden Sie in unserer Bündelungsdokumentation.
Fügen Sie in rollup.config.js
folgende benutzerdefinierte Namensexporte in cjs
Plug-In hinzu.
cjs({
namedExports: {
events: ["EventEmitter"],
"@azure/communication-signaling": ["CommunicationSignalingClient", "SignalingClient"],
"@opentelemetry/api": ["CanonicalCode", "SpanKind", "TraceFlags"]
}
})
Schlüsselkonzepte
Eine Chatunterhaltung wird durch einen Thread dargestellt. Jeder Benutzer im Thread wird als Chatteilnehmer bezeichnet. Chatteilnehmer können privat in einem 1:1-Chat miteinander chatten oder in einem 1:N-Gruppenchat nach oben schieben. Benutzer erhalten außerdem Nahezu-Echtzeitupdates für den Zeitpunkt der Eingabe und beim Lesen der Nachrichten.
ChatClient
ChatClient
ist die primäre Schnittstelle für Entwickler, die diese Clientbibliothek verwenden. Es stellt asynchrone Methoden zum Erstellen und Löschen eines Threads bereit.
ChatThreadClient
ChatThreadClient
bietet asynchrone Methoden zum Ausführen der Nachrichten- und Chatteilnehmervorgänge innerhalb des Chatthreads.
Beispiele
Initialisieren von ChatClient
Verwenden Sie die Ressourcen-URL und das Benutzerzugriffstoken, um den Chatclient zu initialisieren.
import { ChatClient } from '@azure/communication-chat';
import { AzureCommunicationTokenCredential } from "@azure/communication-common";
// Your unique Azure Communication service endpoint
const endpointUrl = '<ENDPOINT>';
const userAccessToken = '<USER_ACCESS_TOKEN>';
const tokenCredential = new AzureCommunicationTokenCredential(userAccessToken);
const chatClient = new ChatClient(endpointUrl, tokenCredential);
Erstellen eines Threads mit zwei Benutzern
Verwenden Sie die createThread
-Methode, um einen Chatthread zu erstellen.
createChatThreadRequest
wird verwendet, um die Threadanforderung zu beschreiben:
- Verwenden Sie
topic
, um ein Threadthema zu geben;
createChatThreadOptions
wird verwendet, um die optionalen Params zum Erstellen des Threads festzulegen:
- Verwenden Sie
participants
, um die Chatteilnehmer auflisten, die dem Thread hinzugefügt werden sollen; - Verwenden von
idempotencyToken
zum Angeben einer wiederholbaren Anforderung
createChatThreadResult
ist das Ergebnis, das vom Erstellen eines Threads zurückgegeben wird. Sie enthält eine chatThread
, die der erstellte Thread ist, sowie eine errors
Eigenschaft, die Informationen zu ungültigen Teilnehmern enthält, wenn sie dem Thread nicht hinzugefügt werden konnten.
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;
Erstellen eines ChatThreadClients
Mit dem ChatThreadClient können Sie Vorgänge ausführen, die speziell für einen Chatthread spezifisch sind, z. B. das Thema zum Aktualisieren des Chatthreads, das Senden einer Nachricht, das Hinzufügen von Teilnehmern zum Chatthread usw.
Sie können einen neuen ChatThreadClient mithilfe der getChatThreadClient
-Methode des ChatClient mit einer vorhandenen Thread-ID initialisieren:
const chatThreadClient = chatClient.getChatThreadClient(threadId);
Senden einer Nachricht an den Thread
Verwenden Sie sendMessage
Methode, um eine Nachricht an einen von threadId identifizierten Thread zu senden.
sendMessageRequest
wird verwendet, um die Nachrichtenanforderung zu beschreiben:
- Verwenden Sie
content
, um den Inhalt von Chatnachrichten bereitzustellen;
sendMessageOptions
wird verwendet, um die optionalen Parameter des Vorgangs zu beschreiben:
- Verwenden Sie
senderDisplayName
, um den Anzeigenamen des Absenders anzugeben; - Verwenden Sie
type
, um den Nachrichtentyp anzugeben, z. B. "Text" oder "html";
sendChatMessageResult
ist das Ergebnis, das vom Senden einer Nachricht zurückgegeben wird, es enthält eine ID, die die eindeutige ID der Nachricht ist.
const sendMessageRequest =
{
content: 'Hello Geeta! Can you share the deck for the conference?'
};
const sendMessageOptions:SendMessageOptions = {
senderDisplayName: "Jack",
type: "text"
};
const sendChatMessageResult = await chatThreadClient.sendMessage(sendMessageRequest, sendMessageOptions);
const messageId = sendChatMessageResult.id;
Empfangen von Nachrichten aus einem Thread
Mit Echtzeitsignalen können Sie die Überwachung neuer eingehender Nachrichten abonnieren und die aktuellen Nachrichten im Arbeitsspeicher entsprechend aktualisieren.
// open notifications channel
await chatClient.startRealtimeNotifications();
// subscribe to new notification
chatClient.on("chatMessageReceived", (e) => {
console.log("Notification chatMessageReceived!");
// your code here
});
Alternativ können Sie Chatnachrichten abrufen, indem Sie die listMessages
Methode in bestimmten Intervallen abrufen.
for await (const chatMessage of chatThreadClient.listMessages()) {
// your code here
}
Hinzufügen von Benutzern zu einem Thread
Nachdem ein Thread erstellt wurde, können Sie Benutzer aus diesem Thread hinzufügen und daraus entfernen. Indem Sie Benutzer hinzufügen, gewähren Sie ihnen Zugriff, um Nachrichten an den Thread zu senden. Zunächst müssen Sie ein neues Zugriffstoken und eine neue Identität für diesen Benutzer abrufen. Der Benutzer benötigt dieses Zugriffstoken, um seinen Chatclient zu initialisieren. Weitere Informationen zu Token hier: Authentifizieren bei Azure Communication Services
const addParticipantsRequest =
{
participants: [
{
id: { communicationUserId: '<NEW_PARTICIPANT_USER_ID>' },
displayName: 'Jane'
}
]
};
await chatThreadClient.addParticipants(addParticipantsRequest);
Entfernen von Benutzern aus einem Thread
Ähnlich wie oben können Sie auch Benutzer aus einem Thread entfernen. Um sie zu entfernen, müssen Sie die IDs der Teilnehmer nachverfolgen, die Sie hinzugefügt haben.
await chatThreadClient.removeParticipant({ communicationUserId: '<MEMBER_ID>' });
Abonnieren des Verbindungsstatus von Echtzeitbenachrichtigungen
Wenn Sie Ereignisse realTimeNotificationConnected
und realTimeNotificationDisconnected
abonnieren, können Sie wissen, wann die Verbindung mit dem Anrufserver aktiv ist.
// 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
});
Fehlerbehebung
Nächste Schritte
In dieser Schnellstartanleitung haben Sie folgendes gelernt:
- Erstellen eines Chatclients
- Erstellen eines Threads mit 2 Benutzern
- Senden einer Nachricht an den Thread
- Empfangen von Nachrichten aus einem Thread
- Entfernen von Benutzern aus einem Thread
Beitragend
Wenn Sie an dieser Bibliothek mitwirken möchten, lesen Sie bitte den mitwirkenden Leitfaden, um mehr über das Erstellen und Testen des Codes zu erfahren.
Azure SDK for JavaScript