Rychlý start: Přidání chatu do aplikace

  • Článek

Začněte se službou Azure Communication Services pomocí sady SDK chatu komunikačních služeb k přidání chatu v reálném čase do aplikace. V tomto rychlém startu pomocí sady SDK chatu vytvoříme vlákna chatu, která uživatelům umožňují vzájemně komunikovat. Další informace o konceptech chatu najdete v koncepční dokumentaci chatu.

Požadavky

  • Účet Azure s aktivním předplatným. Vytvoření účtu zdarma

  • Aktivní prostředek služby Communication Services a připojovací řetězec. Vytvořte prostředek komunikační služby.

  • Nainstalujte Azure CLI.

  • Poznamenejte si koncový bod prostředku komunikační služby. Koncový bod můžete získat z webu Azure Portal. Adresu URL koncového bodu najdete také v připojovací řetězec. Je to adresa URL, která následuje endpoint= a začíná na https://.

  • Přístupový token uživatele. Nezapomeňte nastavit obor pro chat a poznamenejte si řetězec tokenu i řetězec user_id. K vytvoření uživatele a přístupového tokenu můžete také použít Azure CLI a spustit následující příkaz s připojovací řetězec.

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

    Podrobnosti najdete v tématu Použití Azure CLI k vytváření a správě přístupových tokenů.

Nastavení

Přidání rozšíření

Pomocí příkazu přidejte rozšíření Azure Communication Services pro Azure CLI az extension .

az extension add --name communication

Přihlášení k Azure CLI

Budete se muset přihlásit k Azure CLI. Můžete se přihlásit spuštěním az login příkazu z terminálu a zadat své přihlašovací údaje.

(Volitelné) Použití operací identit Azure CLI bez předání koncového bodu nebo přístupového tokenu

Uložení koncového bodu do proměnné prostředí

Proměnnou AZURE_COMMUNICATION_ENDPOINT prostředí můžete nakonfigurovat tak, aby používala operace chatu Azure CLI, aniž byste museli předávat --endpoint koncový bod. Pokud chcete nakonfigurovat proměnnou prostředí, otevřete okno konzoly a na následujících kartách vyberte operační systém. Nahraďte <yourEndpoint> skutečným koncovým bodem.

Otevřete okno konzoly a zadejte následující příkaz:

setx AZURE_COMMUNICATION_ENDPOINT "<yourEndpoint>"

Po přidání proměnné prostředí možná bude nutné restartovat všechny spuštěné programy, které budou potřebovat číst tuto proměnnou prostředí, a to včetně okna konzoly. Pokud například jako editor používáte Sadu Visual Studio, restartujte sadu Visual Studio před spuštěním příkladu.

Uložení přístupového tokenu do proměnné prostředí

Proměnnou AZURE_COMMUNICATION_ACCESS_TOKEN prostředí můžete nakonfigurovat tak, aby používala operace chatu Azure CLI, aniž byste museli předávat --access-token přístupový token. Pokud chcete nakonfigurovat proměnnou prostředí, otevřete okno konzoly a na následujících kartách vyberte operační systém. Nahraďte <yourAccessToken> skutečným přístupovým tokenem.

Otevřete okno konzoly a zadejte následující příkaz:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

Po přidání proměnné prostředí možná bude nutné restartovat všechny spuštěné programy, které budou potřebovat číst tuto proměnnou prostředí, a to včetně okna konzoly. Pokud například jako editor používáte Sadu Visual Studio, restartujte sadu Visual Studio před spuštěním příkladu.

Operace

Zahájení vlákna chatu

thread create Pomocí příkazu vytvořte vlákno chatu.

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

Pokud jste koncový bod a přístupový token uložili do proměnných prostředí, jak je uvedeno výše, nebudete je muset předat do příkazu.

az communication chat thread create --topic "<chatTopic>"
  • Slouží <chatTopic> k poskytnutí tématu ve vlákně. Téma můžete aktualizovat po vytvoření vlákna chatu thread update-topic pomocí příkazu.
  • Nahraďte <endpoint> koncovým bodem služby Azure Communication Services.
  • Nahraďte <token> přístupovým tokenem získaným dříve spuštěním identity token issue příkazu.

Aktualizace tématu vlákna chatu

az communication chat thread update-topic --thread "<chatThreadId>" --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"
  • Nahraďte <chatThreadId> ID vlákna chatu.
  • Nahraďte <chatTopic> novým tématem chatu, které chcete nastavit.
  • Nahraďte <endpoint> koncovým bodem služby Azure Communication Services.
  • Nahraďte <token> přístupovým tokenem získaným dříve spuštěním identity token issue příkazu.

Zobrazení seznamu všech vláken chatu

Příkaz thread list vrátí seznam vláken chatu uživatele.

az communication chat thread list --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Volitelně můžete <startTime> zadat nejstarší bod v čase, abyste mohli dostávat zprávy chatu.
  • Nahraďte <endpoint> koncovým bodem služby Azure Communication Services.
  • Nahraďte <token> přístupovým tokenem získaným dříve spuštěním identity token issue příkazu.

Odeslání zprávy do vlákna chatu

message send Pomocí příkazu odešlete zprávu do vlákna chatu, které jste vytvořili, identifikované uživatelem threadId.

az communication chat message send --thread "<chatThreadId>" --display-name "<displayName>" --content "<content>" --message-type "<messageType>"  --endpoint "<endpoint>" --access-token "<token>"
  • Nahraďte <chatThreadId> ID vlákna chatu.
  • Slouží <content> k poskytnutí obsahu chatové zprávy.
  • Slouží <messageType> k určení typu obsahu zprávy. Možné hodnoty jsou text a html. Pokud nezadáte hodnotu, výchozí hodnota je text.
  • Volitelně můžete <displayName> zadat zobrazované jméno odesílatele.
  • Nahraďte <endpoint> koncovým bodem služby Azure Communication Services.
  • Nahraďte <token> přístupovým tokenem získaným dříve spuštěním identity token issue příkazu.

Výpis zpráv chatu ve vlákně chatu

Příkaz message list vrátí seznam chatových zpráv ve vlákně chatu.

az communication chat message list --thread "<chatThreadId>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Nahraďte <chatThreadId> ID vlákna chatu.
  • Volitelně můžete <startTime> zadat nejstarší bod v čase, abyste mohli dostávat zprávy chatu.
  • Nahraďte <endpoint> koncovým bodem služby Azure Communication Services.
  • Nahraďte <token> přístupovým tokenem získaným dříve spuštěním identity token issue příkazu.

Příjem zprávy chatu z vlákna chatu

Chatové zprávy můžete načíst pomocí message list příkazu.

az communication chat message get --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Nahraďte <chatThreadId> ID vlákna chatu.
  • Nahraďte <messageId> ID zprávy, kterou chcete načíst.
  • Nahraďte <endpoint> koncovým bodem služby Azure Communication Services.
  • Nahraďte <token> přístupovým tokenem získaným dříve spuštěním identity token issue příkazu.

Odeslat potvrzení o přečtení

Pomocí message receipt send příkazu publikujete událost potvrzení o přečtení do vlákna jménem uživatele.

az communication chat message receipt send --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Nahraďte <chatThreadId> ID vlákna chatu.
  • Nahraďte <messageId> tak, že zadáte ID nejnovější zprávy přečtené aktuálním uživatelem.
  • Nahraďte <endpoint> koncovým bodem služby Azure Communication Services.
  • Nahraďte <token> přístupovým tokenem získaným dříve spuštěním identity token issue příkazu.

Přidání uživatele jako účastníka do vlákna chatu

Když vytvoříte vlákno chatu, můžete z něj přidávat a odebírat uživatele. Přidáním uživatelů jim udělíte přístup, aby mohli odesílat zprávy do vlákna chatu a přidávat nebo odebírat další účastníky. Před voláním participant add příkazu se ujistěte, že jste pro daného uživatele získali nový přístupový token a identitu.

az communication chat participant add --thread "<chatThreadId>" --user "<userId>" --display-name "<displayName>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Nahraďte <chatThreadId> ID vlákna chatu.
  • Nahraďte <userId> id uživatele.
  • Volitelně můžete <displayName> zadat zobrazované jméno odesílatele.
  • Volitelně můžete <startTime> zadat nejstarší bod v čase, abyste mohli dostávat zprávy chatu.
  • Nahraďte <endpoint> koncovým bodem služby Azure Communication Services.
  • Nahraďte <token> přístupovým tokenem získaným dříve spuštěním identity token issue příkazu.

Zobrazení seznamu účastníků vlákna ve vlákně chatu

Podobně jako při přidávání účastníka můžete také zobrazit seznam účastníků z vlákna.

Pomocí participant list příkazu načtěte účastníky vlákna.

az communication chat participant list --thread "<chatThreadId>" --skip "<skip>" --endpoint "<endpoint>" --access-token "<token>"
  • Nahraďte <chatThreadId> ID vlákna chatu.
  • Volitelně můžete <skip> účastníky přeskočit na zadanou pozici v odpovědi.
  • Nahraďte <endpoint> koncovým bodem služby Azure Communication Services.
  • Nahraďte <token> přístupovým tokenem získaným dříve spuštěním identity token issue příkazu.

Odebrání účastníka z vlákna chatu

Účastníka chatu můžete z vlákna chatu odebrat pomocí příkazu "účastník odebrat".

az communication chat participant remove --thread "<chatThreadId>" --user "<userId>" --endpoint "<endpoint>" --access-token "<token>"
  • Nahraďte <chatThreadId> ID vlákna chatu.
  • Nahraďte <userId> ID uživatele, které chcete odebrat z vlákna chatu.
  • Nahraďte <endpoint> koncovým bodem služby Azure Communication Services.
  • Nahraďte <token> přístupovým tokenem získaným dříve spuštěním identity token issue příkazu.

Předpoklady

Než začnete, nezapomeňte:

  • Vytvořte účet Azure s aktivním předplatným. Podrobnosti najdete v tématu Vytvoření účtu zdarma.

  • Nainstalujte verze LTS a údržby Node.js Active LTS a Maintenance LTS.

  • Vytvořte zdroj Azure Communication Services. Podrobnosti najdete v tématu Vytvoření prostředku Azure Communication Services. Pro účely tohoto rychlého startu budete muset zaznamenat koncový bod prostředku a připojovací řetězec.

  • Vytvořte tři uživatele služeb Azure Communication Services a zadejte jim přístupový token uživatele. Nezapomeňte nastavit obor pro chat a poznamenejte si řetězec tokenu i řetězec user_id. Úplná ukázka vytvoří vlákno se dvěma počátečními účastníky a pak přidá třetího účastníka do vlákna. K vytvoření uživatele a přístupového tokenu můžete také použít Azure CLI a spustit následující příkaz s připojovací řetězec.

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

    Podrobnosti najdete v tématu Použití Azure CLI k vytváření a správě přístupových tokenů.

Nastavení

Vytvoření nové webové aplikace

Nejprve otevřete terminál nebo příkazové okno, vytvořte pro aplikaci nový adresář a přejděte na něj.

mkdir chat-quickstart && cd chat-quickstart

Spuštěním příkazu npm init -y vytvořte soubor package.json s výchozím nastavením.

npm init -y

Instalace balíčků

npm install Pomocí příkazu nainstalujte následující sady SDK komunikačních služeb pro JavaScript.

npm install @azure/communication-common --save

npm install @azure/communication-identity --save

npm install @azure/communication-signaling --save

npm install @azure/communication-chat --save

Tato --save možnost vypíše knihovnu jako závislost v souboru package.json .

Nastavení architektury aplikace

V tomto rychlém startu se k vytvoření prostředků aplikace používá balík. Spuštěním následujícího příkazu ho nainstalujte a vypište ji jako vývojovou závislost v souboru package.json:

npm install parcel --save-dev

V kořenovém adresáři projektu vytvořte soubor index.html . Tento soubor použijeme jako šablonu k přidání chatu pomocí sady SDK chatu pro Azure Communication Chat pro 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>

V kořenovém adresáři projektu vytvořte soubor s názvem client.js , který bude obsahovat logiku aplikace pro účely tohoto rychlého startu.

Vytvoření chatovacího klienta

K vytvoření chatovacího klienta ve webové aplikaci použijete koncový bod komunikační služby a přístupový token, který se vygeneroval v rámci požadovaných kroků.

Přístupové tokeny uživatelů umožňují vytvářet klientské aplikace, které se přímo ověřují ve službě Azure Communication Services. Tento rychlý start nepokrývá vytvoření úrovně služby pro správu tokenů pro chatovací aplikaci. Další informace o architektuře chatu a přístupových tokenech uživatelů najdete v konceptech chatu.

V souboru client.js použijte koncový bod a přístupový token v níže uvedeném kódu a přidejte chatovací funkce pomocí sady SDK služby Azure Communication Chat pro 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!');
  • Nahraďte koncový bod koncovým bodem prostředku služby Communication Services. Pokud jste to ještě neudělali, přečtěte si téma Vytvoření prostředku služby Azure Communication Services.
  • Nahraďte userAccessToken tokenem, který jste vydali.

Spuštění kódu

Spuštěním následujícího příkazu spusťte aplikaci:

npx parcel index.html

Otevřete prohlížeč a přejděte na http://localhost:1234/. V konzole vývojářských nástrojů v prohlížeči byste měli vidět následující:

Azure Communication Chat client created!

Objektový model

Následující třídy a rozhraní zpracovávají některé z hlavních funkcí sady AZURE Communication Services Chat SDK pro JavaScript.

Název Popis
ChatClient Tato třída je potřebná pro funkci Chat. Vytvoříte instanci s informacemi o předplatném a použijete je k vytvoření, získání, odstranění vláken a přihlášení k odběru událostí chatu.
ChatThreadClient Tato třída je potřebná pro funkci vlákna chatu. Instanci získáte prostřednictvím ChatClient a použijete ji k odesílání, přijímání, aktualizaci, odstraňování zpráv, přidávání, odebírání nebo získávání uživatelů, odesílání oznámení o psaní a potvrzení o přečtení.

Zahájení vlákna chatu

Použijte metodu createThread k vytvoření vlákna chatu.

createThreadRequest slouží k popisu požadavku na vlákno:

  • Slouží topic k poskytnutí tématu pro tento chat. Témata je možné aktualizovat po vytvoření vlákna chatu UpdateThread pomocí funkce.
  • Umožňuje participants zobrazit seznam účastníků, které se mají přidat do vlákna chatu.

Při vyřešení createChatThread vrátí CreateChatThreadResultmetoda hodnotu . Tento model obsahuje chatThread vlastnost, ke které máte přístup k nově vytvořenému vláknu id . Pak můžete použít id k získání instance objektu ChatThreadClient. Pak ChatThreadClient se dá použít k provedení operace v rámci vlákna, jako je odesílání zpráv nebo výpis účastníků.

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

Když aktualizujete kartu prohlížeče, měli byste v konzole vidět následující:

Thread created: <thread_id>

Získání klienta vlákna chatu

Metoda getChatThreadClient vrátí chatThreadClient pro vlákno, které již existuje. Dá se použít k provádění operací ve vytvořeném vlákně: přidání účastníků, odeslání zprávy atd. threadId je jedinečné ID existujícího vlákna chatu.

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

Přidejte tento kód místo <CREATE CHAT THREAD CLIENT> komentáře v client.js, aktualizujte kartu prohlížeče a zkontrolujte konzolu, měli byste vidět:

Chat Thread client for threadId: <threadId>

Zobrazení seznamu všech vláken chatu

Metoda listChatThreads vrátí PagedAsyncIterableIterator typ ChatThreadItem. Dá se použít pro výpis všech vláken chatu. Iterátorem [ChatThreadItem] je odpověď vrácená z výpisu vláken.

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

Odeslání zprávy do vlákna chatu

Metoda slouží sendMessage k odeslání zprávy do vlákna identifikovaného identifikátorem threadId.

sendMessageRequest slouží k popisu žádosti o zprávu:

  • Slouží content k poskytnutí obsahu chatové zprávy;

sendMessageOptions slouží k popisu volitelného parametru operace:

  • Slouží senderDisplayName k určení zobrazovaného jména odesílatele;
  • Slouží type k určení typu zprávy, například "text" nebo "html";
  • Volitelně můžete metadata zahrnout všechna další data, která chcete spolu se zprávou odeslat. Toto pole poskytuje vývojářům mechanismus pro rozšíření funkčnosti chatových zpráv a přidání vlastních informací pro váš případ použití. Například při sdílení odkazu na soubor ve zprávě můžete přidat "hasAttachment: true" v metadatech, aby aplikace příjemce mohla parsovat a zobrazit odpovídajícím způsobem.

SendChatMessageResult je odpověď vrácená odesláním zprávy, obsahuje ID, což je jedinečné ID zprávy.

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

Přidejte tento kód místo <SEND MESSAGE TO A CHAT THREAD> komentáře v client.js, aktualizujte kartu prohlížeče a zkontrolujte konzolu.

Message sent!, message id:<number>

Příjem zpráv chatu z vlákna chatu

Díky signalizaci v reálném čase se můžete přihlásit k odběru nových příchozích zpráv a odpovídajícím způsobem aktualizovat aktuální zprávy v paměti. Azure Communication Services podporuje seznam událostí, ke kterým se můžete přihlásit.

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

Přidejte tento kód místo <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD> komentáře v client.js. Aktualizujte kartu prohlížeče, měli byste vidět v konzole zprávu Notification chatMessageReceived;

Případně můžete načíst chatové zprávy dotazováním listMessages metody v zadaných intervalech.


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

Přidejte tento kód místo <LIST MESSAGES IN A CHAT THREAD> komentáře v client.js. Aktualizujte kartu v konzole, ve které byste měli najít seznam zpráv odeslaných v tomto vlákně chatu.

listMessages vrátí různé typy zpráv, které lze identifikovat chatMessage.typepomocí .

Další podrobnosti najdete v tématu Typy zpráv.

Přidání uživatele jako účastníka do vlákna chatu

Jakmile se vytvoří vlákno chatu, můžete z něj přidávat a odebírat uživatele. Přidáním uživatelů jim udělíte přístup k odesílání zpráv do vlákna chatu a přidáte nebo odeberete další účastníky.

Před voláním addParticipants metody se ujistěte, že jste pro daného uživatele získali nový přístupový token a identitu. Uživatel bude tento přístupový token potřebovat k inicializaci svého chatovacího klienta.

addParticipantsRequest popisuje objekt požadavku, ve kterém je participants uveden seznam účastníků, kteří mají být přidáni do vlákna chatu;

  • id, je povinný identifikátor komunikace, který se má přidat do vlákna chatu.
  • displayName, volitelné, je zobrazovaný název účastníka vlákna.
  • shareHistoryTime, volitelné, je čas, ze kterého se historie chatu sdílí s účastníkem. Chcete-li sdílet historii od vzniku vlákna chatu, nastavte tuto vlastnost na libovolné datum, které se rovná nebo menší než čas vytvoření vlákna. Pokud chcete sdílet žádnou historii, ke které došlo při přidání účastníka, nastavte ji na aktuální datum. Pokud chcete sdílet částečnou historii, nastavte ji na datum podle vašeho výběru.

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

await chatThreadClient.addParticipants(addParticipantsRequest);

Nahraďte NEW_PARTICIPANT_USER_IDnovým ID uživatele Přidat tento kód místo <ADD NEW PARTICIPANT TO THREAD> komentáře v client.js

Zobrazení seznamu uživatelů ve vlákně chatu

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

Přidejte tento kód místo <LIST PARTICIPANTS IN A THREAD> komentáře v client.js, aktualizujte kartu prohlížeče a zkontrolujte konzolu, měli byste vidět informace o uživatelích ve vlákně.

Odebrání uživatele z vlákna chatu

Podobně jako přidání účastníka můžete odebrat účastníky z vlákna chatu. Abyste mohli odebrat, budete muset sledovat ID účastníků, které jste přidali.

Použijte removeParticipant metodu, kde participant je komunikační uživatel, který se má odebrat z vlákna.


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

Nahraďte PARTICIPANT_ID ID uživatele použitým v předchozím kroku (<NEW_PARTICIPANT_USER_ID>). Přidejte tento kód místo <REMOVE PARTICIPANT FROM THREAD> komentáře v client.js.

Přihlášení k odběru stavu připojení oznámení v reálném čase

Odběr událostí realTimeNotificationConnected a realTimeNotificationDisconnected umožňuje zjistit, kdy je připojení k volajícímu serveru aktivní.

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

Ukázka kódu

Najděte finalizovaný kód pro tento rychlý start na GitHubu.

Předpoklady

Než začnete, nezapomeňte:

  • Vytvořte účet Azure s aktivním předplatným. Podrobnosti najdete v tématu Vytvoření účtu zdarma.

  • Nainstalujte Python 3.7 nebo novější.

  • Vytvořte zdroj Azure Communication Services. Podrobnosti najdete v tématu Rychlý start: Vytvoření a správa prostředků komunikačních služeb. Pro účely tohoto rychlého startu budete muset zaznamenat koncový bod prostředku a připojovací řetězec.

  • Přístupový token uživatele. Nezapomeňte nastavit obor pro chat a poznamenejte si řetězec tokenu i řetězec user_id. K vytvoření uživatele a přístupového tokenu můžete také použít Azure CLI a spustit následující příkaz s připojovací řetězec.

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

    Podrobnosti najdete v tématu Použití Azure CLI k vytváření a správě přístupových tokenů.

Nastavení

Vytvoření nové aplikace v Pythonu

Otevřete terminál nebo příkazové okno, vytvořte pro aplikaci nový adresář a přejděte na něj.

mkdir chat-quickstart && cd chat-quickstart

Pomocí textového editoru vytvořte soubor s názvem start-chat.py v kořenovém adresáři projektu. Přidejte strukturu pro program, včetně základního zpracování výjimek. V následujících částech přidáte do tohoto souboru veškerý zdrojový kód pro tento rychlý start.

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)

Instalace sady SDK

K instalaci sady SDK použijte následující příkaz:


pip install azure-communication-chat

Objektový model

Následující třídy a rozhraní zpracovávají některé z hlavních funkcí sady AZURE Communication Services Chat SDK pro Python.

Název Popis
ChatClient Tato třída je potřebná pro funkci chatu. Vytvoříte instanci s informacemi o předplatném a použijete je k vytvoření, získání a odstranění vláken.
ChatThreadClient Tato třída je potřebná pro funkci vlákna chatu. Instanci získáte prostřednictvím ChatClienta použijete ji k odesílání, přijímání, aktualizaci a odstraňování zpráv. Můžete ho také použít k přidávání, odebírání a získávání uživatelů a posílání oznámení a potvrzení o přečtení.

Vytvoření chatovacího klienta

K vytvoření chatovacího klienta použijte koncový bod komunikační služby a přístupový token, který jste vygenerovali v rámci požadovaných kroků.

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>"))

Tento rychlý start nepokrývá vytvoření úrovně služby pro správu tokenů pro chatovací aplikaci, ale doporučuje se. Další informace najdete v části Architektura chatu v konceptech chatu.

Zahájení vlákna chatu

Použijte metodu create_chat_thread k vytvoření vlákna chatu.

  • Slouží topic k poskytnutí tématu ve vlákně. Téma můžete aktualizovat po vytvoření vlákna chatu update_thread pomocí funkce.
  • Umožňuje thread_participants vypsat seznam, který ChatParticipant se má přidat do vlákna chatu. Typ ChatParticipant přebírá CommunicationUserIdentifier jako user.

CreateChatThreadResult je výsledek vrácený z vytvoření vlákna. Můžete ho použít k načtení id vytvořeného vlákna chatu. To id se pak dá použít k načtení objektu ChatThreadClientget_chat_thread_client pomocí metody. V tomto vlákně chatu můžete provádět ChatThreadClient další operace chatu.

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)

Získání klienta vlákna chatu

Metoda get_chat_thread_client vrátí klienta vlákna pro vlákno, které již existuje. Můžete ho použít k provádění operací ve vytvořeném vlákně. Můžete například přidat účastníky a posílat zprávy. thread_id je jedinečné ID existujícího vlákna chatu.

V tomto vlákně chatu můžete provádět ChatThreadClient další operace chatu.

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

Zobrazení seznamu všech vláken chatu

Metoda list_chat_threads vrátí iterátor typu ChatThreadItem.

  • Slouží start_time k určení nejstaršího bodu v čase pro získání vláken chatu.
  • Slouží results_per_page k určení maximálního počtu vláken chatu vrácených na stránku.

Iterátorem [ChatThreadItem] je odpověď vrácená z výpisu vláken.

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)

Odeslání zprávy do vlákna chatu

send_message Pomocí metody odešlete zprávu do vlákna chatu, které jste právě vytvořili, identifikovaný .thread_id

  • Slouží content k poskytnutí obsahu chatové zprávy.
  • Slouží chat_message_type k určení typu obsahu zprávy. Možné hodnoty jsou text a html. Pokud nezadáte hodnotu, výchozí hodnota je text.
  • Slouží sender_display_name k zadání zobrazovaného jména odesílatele.
  • Volitelně můžete metadata zahrnout všechna další data, která chcete spolu se zprávou odeslat. Toto pole poskytuje vývojářům mechanismus pro rozšíření funkčnosti chatových zpráv a přidání vlastních informací pro váš případ použití. Například při sdílení odkazu na soubor ve zprávě můžete do metadat přidat "hasAttachment:true", aby aplikace příjemce mohla odpovídajícím způsobem parsovat a zobrazit.

SendChatMessageResult je odpověď vrácená odesláním zprávy. Obsahuje ID, což je jedinečné ID zprávy.

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)

Příjem zpráv chatu z vlákna chatu

Chatové zprávy můžete načíst dotazováním list_messages metody v zadaných intervalech.

  • Slouží results_per_page k určení maximálního počtu zpráv, které se mají vrátit na stránku.
  • Slouží start_time k určení nejstaršího bodu v čase pro získání zpráv.

Iterátorem [ChatMessage] je odpověď vrácená výpisem zpráv.

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 vrátí nejnovější verzi zprávy, včetně všech úprav nebo odstranění, které se stalo se zprávou pomocí update_message a delete_message. U odstraněných zpráv ChatMessage.deleted_on vrátí datetime hodnotu označující, kdy byla tato zpráva odstraněna. U upravených zpráv ChatMessage.edited_on vrátí datetime hodnotu označující, kdy byla zpráva upravena. K původnímu času vytvoření zprávy můžete přistupovat pomocí příkazu ChatMessage.created_on, který lze použít k řazení zpráv.

list_messages vrací různé typy zpráv, které lze identifikovat ChatMessage.type.

Další informace naleznete v tématu Typy zpráv.

Odeslat potvrzení o přečtení

Tuto metodu send_read_receipt použijete k publikování události potvrzení o přečtení do vlákna jménem uživatele.

  • Slouží message_id k zadání ID nejnovější zprávy přečtené aktuálním uživatelem.
content='hello world'

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

Přidání uživatele jako účastníka do vlákna chatu

Když vytvoříte vlákno chatu, můžete z něj přidávat a odebírat uživatele. Přidáním uživatelů jim udělíte přístup, aby mohli odesílat zprávy do vlákna chatu a přidávat nebo odebírat další účastníky. Před voláním add_participants metody se ujistěte, že jste získali nový přístupový token a identitu pro daného uživatele. Aby uživatel inicializoval chatovacího klienta, potřebuje tento přístupový token.

Pomocí metody můžete přidat jednoho nebo více uživatelů do vlákna add_participants chatu za předpokladu, že je pro všechny uživatele k dispozici nový přístupový token a identita.

Vrátí se hodnota A list(tuple(ChatParticipant, CommunicationError)) . Po úspěšném přidání účastníka se očekává prázdný seznam. Pokud při přidávání účastníka dojde k chybě, seznam se naplní neúspěšnými účastníky spolu s chybou, ke které došlo.

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)

Zobrazení seznamu účastníků vlákna ve vlákně chatu

Podobně jako při přidávání účastníka můžete také zobrazit seznam účastníků z vlákna.

Slouží list_participants k načtení účastníků vlákna. Oba následující příkazy jsou volitelné:

  • Slouží results_per_page k určení maximálního počtu účastníků, které se mají vrátit na stránku.
  • Slouží skip k přeskočení účastníků na zadanou pozici v odpovědi.

Iterátorem [ChatParticipant] je odpověď vrácená ze výpisu účastníků.

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)

Spuštění kódu

Spusťte aplikaci z adresáře aplikace pomocí python příkazu.

python start-chat.py

Ukázka kódu

Najděte finalizovaný kód pro tento rychlý start na GitHubu.

Požadavky

Nastavení

Vytvoření nové aplikace v Javě

Otevřete terminál nebo příkazové okno a přejděte do adresáře, do kterého chcete vytvořit aplikaci v Javě. Spuštěním následujícího příkazu vygenerujte projekt Java ze šablony maven-archetype-quickstart.

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

Všimněte si, že cíl generování vytvořil adresář se stejným názvem jako artifactId. V tomto adresáři src/main/java directory obsahuje zdrojový kód projektu, src/test/java adresář obsahuje testovací zdroj a soubor pom.xml je projektový objektový model nebo POM.

Aktualizujte soubor POM vaší aplikace tak, aby používal Javu 8 nebo vyšší:

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

Přidání odkazů na balíčky pro chatovací sadu SDK

V souboru POM odkazujte na azure-communication-chat balíček pomocí rozhraní API chatu:

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

Pro ověření musí váš klient odkazovat na azure-communication-common balíček:

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

Objektový model

Následující třídy a rozhraní zpracovávají některé z hlavních funkcí sady AZURE Communication Services Chat SDK pro Javu.

Název Popis
ChatClient Tato třída je potřebná pro funkci Chat. Vytvoříte instanci s informacemi o předplatném a použijete je k vytvoření, získání a odstranění vláken.
ChatAsyncClient Tato třída je potřebná pro asynchronní funkce chatu. Vytvoříte instanci s informacemi o předplatném a použijete je k vytvoření, získání a odstranění vláken.
ChatThreadClient Tato třída je potřebná pro funkci vlákna chatu. Instanci získáte prostřednictvím ChatClient a použijete ji k odesílání, přijímání, aktualizaci, odstraňování zpráv, přidávání, odebírání nebo získávání uživatelů, odesílání oznámení o psaní a potvrzení o přečtení.
ChatThreadAsyncClient Tato třída je potřebná pro asynchronní funkci vlákna chatu. Instanci získáte prostřednictvím ChatAsyncClient a použijete ji k odesílání, příjmu, aktualizaci, odstraňování zpráv, přidávání, odebírání nebo získávání uživatelů, posílání oznámení o psaní a potvrzení o přečtení.

Vytvoření chatovacího klienta

K vytvoření chatovacího klienta použijete koncový bod komunikační služby a přístupový token, který se vygeneroval v rámci požadovaných kroků. Přístupové tokeny uživatelů umožňují vytvářet klientské aplikace, které se přímo ověřují ve službě Azure Communication Services. Jakmile tyto tokeny vygenerujete na serveru, předejte je zpět do klientského zařízení. K předání tokenu chatovacímu klientovi musíte použít třídu CommunicationTokenCredential ze sady Common SDK.

Další informace o architektuře chatu

Při přidávání příkazů importu nezapomeňte přidat pouze importy z oboru názvů com.azure.communication.chat a com.azure.communication.chat.models, a ne z oboru názvů com.azure.communication.chat.implementation. V souboru App.java, který byl vygenerován prostřednictvím Mavenu, můžete začít následujícím kódem:

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

Zahájení vlákna chatu

Použijte metodu createChatThread k vytvoření vlákna chatu. createChatThreadOptions slouží k popisu požadavku na vlákno.

  • topic Pomocí parametru konstruktoru dejte tématu do tohoto chatu; Téma je možné aktualizovat po vytvoření vlákna chatu UpdateThread pomocí funkce.
  • Slouží participants k zobrazení seznamu účastníků vlákna, které se mají přidat do vlákna. ChatParticipant vezme uživatele, který jste vytvořili v rychlém startu tokenu přístupu uživatele.

CreateChatThreadResult je odpověď vrácená z vytvoření vlákna chatu. Obsahuje metodu getChatThread()ChatThread , která vrací objekt, který lze použít k získání klienta vlákna, ze kterého můžete získat ChatThreadClient pro provádění operací ve vytvořeném vlákně: přidání účastníků, odeslání zprávy atd. Objekt ChatThread také obsahuje metodu getId() , která načte jedinečné ID vlákna.

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

Seznam vláken chatu

listChatThreads Pomocí této metody můžete načíst seznam existujících vláken chatu.

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

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

Získání klienta vlákna chatu

Metoda getChatThreadClient vrátí klienta vlákna pro vlákno, které již existuje. Dá se použít k provádění operací ve vytvořeném vlákně: přidání účastníků, odeslání zprávy atd. chatThreadId je jedinečné ID existujícího vlákna chatu.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Odeslání zprávy do vlákna chatu

sendMessage Pomocí metody odešlete zprávu do vlákna, které jste vytvořili, identifikované chatThreadId. sendChatMessageOptions slouží k popisu žádosti o chatovou zprávu.

  • Slouží content k poskytnutí obsahu chatové zprávy.
  • Slouží type k určení typu obsahu zprávy chatu, TEXT nebo HTML.
  • Slouží senderDisplayName k zadání zobrazovaného jména odesílatele.
  • Volitelně můžete metadata zahrnout všechna další data, která chcete spolu se zprávou odeslat. Toto pole poskytuje vývojářům mechanismus pro rozšíření funkčnosti chatových zpráv a přidání vlastních informací pro váš případ použití. Například při sdílení odkazu na soubor ve zprávě můžete chtít přidat hasAttachment:true metadata, aby aplikace příjemce mohla parsovat a zobrazovat odpovídajícím způsobem.

Odpověď sendChatMessageResult obsahuje idjedinečné ID zprávy.

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

Příjem zpráv chatu z vlákna chatu

Chatové zprávy můžete načíst dotazováním listMessages metody v klientovi vlákna chatu v zadaných intervalech.

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

listMessages vrátí nejnovější verzi zprávy, včetně všech úprav nebo odstranění, které se stalo se zprávou pomocí .editMessage() a .deleteMessage(). U odstraněných zpráv chatMessage.getDeletedOn() vrátí hodnotu datetime označující, kdy byla tato zpráva odstraněna. U upravených zpráv vrátí datum a čas označující chatMessage.getEditedOn() , kdy byla zpráva upravena. K původnímu času vytvoření zprávy lze přistupovat pomocí chatMessage.getCreatedOn()a lze ho použít k řazení zpráv.

Další informace o typech zpráv najdete tady: Typy zpráv.

Odeslat potvrzení o přečtení

sendReadReceipt Metoda slouží k publikování události potvrzení o přečtení do vlákna chatu jménem uživatele. chatMessageId je jedinečné ID přečtené zprávy chatu.

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

Výpis účastníků chatu

Slouží listParticipants k načtení stránkované kolekce obsahující účastníky vlákna chatu identifikovaných chatemThreadId.

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

Přidání uživatele jako účastníka do vlákna chatu

Jakmile se vytvoří vlákno chatu, můžete z něj přidávat a odebírat uživatele. Přidáním uživatelů jim udělíte přístup k odesílání zpráv do vlákna chatu a přidáte nebo odeberete další účastníky. Musíte začít získáním nového přístupového tokenu a identity pro daného uživatele. Před voláním metody addParticipants se ujistěte, že jste získali nový přístupový token a identitu pro daného uživatele. Uživatel bude tento přístupový token potřebovat k inicializaci svého chatovacího klienta.

Použijte metodu addParticipants pro přidání účastníků do vlákna.

  • communicationIdentifier, povinné, je CommunicationIdentifier, který jste vytvořili CommunicationIdentityClient v rychlém startu tokenu přístupu uživatele.
  • displayName, volitelné, je zobrazovaný název účastníka vlákna.
  • shareHistoryTime, volitelné, je čas, ze kterého se historie chatu sdílí s účastníkem. Chcete-li sdílet historii od vzniku vlákna chatu, nastavte tuto vlastnost na libovolné datum, které se rovná nebo menší než čas vytvoření vlákna. Pokud chcete sdílet žádnou historii, ke které došlo při přidání účastníka, nastavte ji na aktuální datum. Pokud chcete sdílet částečnou historii, nastavte ji na požadované datum.
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);

Spuštění kódu

Pomocí následujícího mvn příkazu přejděte do adresáře obsahujícího soubor pom.xml a zkompilujte projekt.

mvn compile

Pak balíček sestavte.

mvn package

Spuštěním následujícího mvn příkazu spusťte aplikaci.

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

Ukázka kódu

Najděte finalizovaný kód pro tento rychlý start na GitHubu.

Předpoklady

Než začnete, nezapomeňte:

Nastavení

Vytvoření nové aplikace pro Android

  1. Otevřete Android Studio a vyberte Create a new project.
  2. V dalším okně vyberte Empty Activity jako šablonu projektu.
  3. Při výběru možností zadejte ChatQuickstart jako název projektu.
  4. Klikněte na další a zvolte adresář, do kterého chcete projekt vytvořit.

Instalace knihoven

K instalaci potřebných závislostí komunikačních služeb použijeme Gradle. Z příkazového řádku přejděte do kořenového ChatQuickstart adresáře projektu. Otevřete soubor build.gradle aplikace a přidejte do ChatQuickstart cíle následující závislosti:

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

Přečtěte si a https://search.maven.org/artifact/com.azure.android/azure-communication-chat podívejte se na https://search.maven.org/artifact/com.azure.android/azure-communication-common nejnovější čísla verzí.

Vyloučení metasou souborů v možnostech balení v kořenovém build.gradle

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")
    }
}

(Alternativní) Instalace knihoven prostřednictvím Mavenu

Pokud chcete knihovnu importovat do projektu pomocí buildového systému Maven , přidejte ji do dependencies oddílu souboru vaší aplikace pom.xml a zadejte JEHO ID artefaktu a verzi, kterou chcete použít:

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

Nastavení funkce Azure

Podrobnosti najdete v integraci funkce Azure Functions. Důrazně doporučujeme integrovat se službou Azure Functions, abyste se vyhnuli pevně zakódování parametrů aplikace.

Nastavení konstant aplikace:

Vytvořte třídu ApplicationConstants , která ukládá všechny konstanty aplikace:

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

Nastavení zástupných symbolů

Otevřete a upravte soubor MainActivity.java. V tomto rychlém startu přidáme náš kód do MainActivitya zobrazíme výstup v konzole. Tento rychlý start se nezabývá sestavením uživatelského rozhraní. V horní části souboru naimportujte Azure Communication Commona Azure Communication Chatdalší systémové knihovny:

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;

Zkopírujte následující kód do třídy MainActivity v souboru 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());
        }
    }

Inicializace parametrů aplikace

Poznámka:

Inicializace ApplicationConstants musí být přidána, MainActivity.java pokud je splněna některé z následujících podmínek: 1. Funkce nabízených oznámení není povolená. 2. Verze knihovny Azure Communication Chat pro Android je < 2.0.0. V opačném případě si přečtěte krok 11 v nabízených oznámeních androidu. Projděte si ukázkovou aplikaci verze sady SDK, kterou používáte pro referenci.

ACS_ENDPOINTFIRST_USER_ID a FIRST_USER_ACCESS_TOKEN vrací se z volání funkce Azure Functions. Podrobnosti najdete v integraci funkce Azure Functions. K inicializaci seznamu parametrů používáme odpověď volání funkce Azure Functions:

  • ACS_ENDPOINT: koncový bod vašeho prostředku komunikační služby.
  • FIRST_USER_ID a SECOND_USER_ID: platná ID uživatelů komunikačních služeb vygenerovaná prostředkem služby Communication Services.
  • FIRST_USER_ACCESS_TOKEN: přístupový token komunikační služby pro <FIRST_USER_ID>.

Blok kódu pro inicializace parametrů aplikace voláním funkce Azure Functions:

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

Vytvoření chatovacího klienta

Nahraďte komentář <CREATE A CHAT CLIENT> následujícím kódem (vložte příkazy importu do horní části souboru):

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

Objektový model

Následující třídy a rozhraní zpracovávají některé z hlavních funkcí sady AZURE Communication Services Chat SDK pro JavaScript.

Název Popis
ChatClient/ChatAsyncClient Tato třída je potřebná pro funkci Chat. Vytvoříte instanci s informacemi o předplatném a použijete je k vytvoření, získání, odstranění vláken a přihlášení k odběru událostí chatu.
ChatThreadClient /ChatThreadAsyncClient Tato třída je potřebná pro funkci vlákna chatu. Instanci získáte prostřednictvím ChatClient a použijete ji k odesílání, přijímání, aktualizaci, odstraňování zpráv, přidávání, odebírání nebo získávání uživatelů, odesílání oznámení o psaní a potvrzení o přečtení.

Zahájení vlákna chatu

Použijeme k ChatAsyncClient vytvoření nového vlákna s počátečním uživatelem.

Nahraďte komentář <CREATE A CHAT THREAD> následujícím kódem:

// 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();

Získání klienta vlákna chatu

Teď, když jsme vytvořili vlákno chatu, získáme ChatThreadAsyncClient operaci v rámci vlákna. Nahraďte komentář <CREATE A CHAT THREAD CLIENT> následujícím kódem:

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

Odeslání zprávy do vlákna chatu

Teď pošleme zprávu do daného vlákna.

Nahraďte komentář <SEND A MESSAGE> následujícím kódem:

// 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();

Příjem zpráv chatu z vlákna chatu

Oznámení v reálném čase

Díky signalizaci v reálném čase se můžete přihlásit k odběru nových příchozích zpráv a odpovídajícím způsobem aktualizovat aktuální zprávy v paměti. Azure Communication Services podporuje seznam událostí, ke kterým se můžete přihlásit.

Nahraďte komentář <RECEIVE CHAT MESSAGES> následujícím kódem (vložte příkazy importu do horní části souboru):


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

Důležité

Známý problém: Při společném používání chatu a volání sady SDK pro Android ve stejné aplikaci nefunguje funkce oznámení sady Chat SDK v reálném čase. Může se stát, že se problém vyřeší pomocí závislosti. Zatímco pracujeme na řešení, můžete funkci oznámení v reálném čase vypnout tak, že do souboru build.gradle aplikace přidáte následující informace o závislostech a místo toho se na rozhraní GetMessages API dotazujete, aby se uživatelům zobrazovaly příchozí zprávy.

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'

Poznámka s výše aktualizací, pokud se aplikace pokusí kontaktovat některé z rozhraní API oznámení, jako chatAsyncClient.startRealtimeNotifications() nebo chatAsyncClient.addEventHandler(), dojde k chybě za běhu.

Nabízená oznámení

Podrobnosti najdete v nabízených oznámeních androidu.

Přidání uživatele jako účastníka do vlákna chatu

Nahraďte komentář <ADD A USER> následujícím kódem:

// 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);

Zobrazení seznamu uživatelů ve vlákně

<LIST USERS> Nahraďte komentář následujícím kódem (vložte příkazy importu do horní části souboru):

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

Odebrání uživatele z vlákna chatu

Teď z vlákna odebereme druhého uživatele.

Nahraďte komentář <REMOVE A USER> následujícím kódem:

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

Odeslání typového oznámení

Nahraďte komentář <SEND A TYPING NOTIFICATION> následujícím kódem:

chatThreadAsyncClient.sendTypingNotification().get();

Odeslání potvrzení o přečtení

Odešleme potvrzení o přečtení zprávy odeslané výše.

Nahraďte komentář <SEND A READ RECEIPT> následujícím kódem:

chatThreadAsyncClient.sendReadReceipt(chatMessageId).get();

Výpis potvrzení o přečtení

Nahraďte komentář <READ RECEIPTS> následujícím kódem:

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

Spuštění kódu

V Android Studiu stiskněte tlačítko Spustit a sestavte a spusťte projekt. V konzole můžete zobrazit výstup z kódu a výstup protokolovacího modulu z ChatClient.

Ukázka kódu

Najděte finalizovaný kód pro tento rychlý start na GitHubu.

Předpoklady

Než začnete, nezapomeňte:

  • Vytvořte účet Azure s aktivním předplatným. Podrobnosti najdete v tématu Vytvoření účtu zdarma.

  • Nainstalovat Visual Studio

  • Vytvořte zdroj Azure Communication Services. Podrobnosti najdete v tématu Vytvoření prostředku Azure Communication Services. V tomto rychlém startu budete muset zaznamenat koncový bod prostředku a připojovací řetězec.

  • Přístupový token uživatele. Nezapomeňte nastavit obor pro chat a poznamenejte si řetězec tokenu i řetězec user_id. K vytvoření uživatele a přístupového tokenu můžete také použít Azure CLI a spustit následující příkaz s připojovací řetězec.

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

    Podrobnosti najdete v tématu Použití Azure CLI k vytváření a správě přístupových tokenů.

Nastavení

Vytvoření nové aplikace jazyka C#

V okně konzoly (například cmd, PowerShell nebo Bash) pomocí dotnet new příkazu vytvořte novou konzolovou aplikaci s názvem ChatQuickstart. Tento příkaz vytvoří jednoduchý projekt "Hello World" C# s jedním zdrojovým souborem: Program.cs.

dotnet new console -o ChatQuickstart

Změňte adresář na nově vytvořenou složku aplikace a pomocí dotnet build příkazu zkompilujte aplikaci.

cd ChatQuickstart
dotnet build

Nainstalujte balíček .

Instalace sady SDK služby Azure Communication Chat pro .NET

dotnet add package Azure.Communication.Chat

Objektový model

Následující třídy zpracovávají některé z hlavních funkcí sady SDK chatu služby Azure Communication Services pro jazyk C#.

Název Popis
ChatClient Tato třída je potřebná pro funkci Chat. Vytvoříte instanci s informacemi o předplatném a použijete je k vytvoření, získání a odstranění vláken.
ChatThreadClient Tato třída je potřebná pro funkci vlákna chatu. Instanci získáte přes ChatClient a použijete ji k odesílání, přijímání, aktualizaci, odstraňování zpráv, přidávání, odebírání nebo získávání účastníků, odesílání oznámení o psaní a potvrzení o přečtení.

Vytvoření chatovacího klienta

K vytvoření chatovacího klienta použijete koncový bod komunikační služby a přístupový token, který se vygeneroval v rámci kroků požadavků. K vytvoření uživatele a vydání tokenu pro předání chatovacímu klientovi musíte použít CommunicationIdentityClient třídu ze sady SDK identity.

Přečtěte si další informace o tokenech přístupu uživatelů.

Tento rychlý start nepokrývá vytvoření úrovně služby pro správu tokenů pro chatovací aplikaci, i když se doporučuje. Další informace o architektuře chatu

Zkopírujte následující fragmenty kódu a vložte je do zdrojového souboru: 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);
        }
    }
}

Zahájení vlákna chatu

createChatThread Použití metody v chatClient k vytvoření vlákna chatu

  • Slouží topic k poskytnutí tématu k tomuto chatu; Téma je možné aktualizovat po vytvoření vlákna chatu UpdateTopic pomocí funkce.
  • Vlastnost slouží participants k předání seznamu ChatParticipant objektů, které se mají přidat do vlákna chatu. Objekt ChatParticipant je inicializován objektem CommunicationIdentifier . CommunicationIdentifier může být typu CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier nebo PhoneNumberIdentifier. Pokud například chcete získat CommunicationIdentifier objekt, budete muset předat přístupové ID, které jste vytvořili podle pokynů k vytvoření uživatele.

Objekt odpovědi z createChatThread metody obsahuje chatThread podrobnosti. Pokud chcete pracovat s operacemi vlákna chatu, jako je přidání účastníků, odeslání zprávy, odstranění zprávy atd., chatThreadClient musí instance klienta vytvořit instanci pomocí GetChatThreadClient metody na klientovi 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;

Získání klienta vlákna chatu

Metoda GetChatThreadClient vrátí klienta vlákna pro vlákno, které již existuje. Dá se použít k provádění operací ve vytvořeném vlákně: přidání členů, odeslání zprávy atd. threadId je jedinečné ID existujícího vlákna chatu.

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

Zobrazení seznamu všech vláken chatu

Slouží GetChatThreads k načtení všech vláken chatu, na které je uživatel součástí.

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

Odeslání zprávy do vlákna chatu

Slouží SendMessage k odeslání zprávy do vlákna.

  • Slouží content k zadání obsahu zprávy, je to povinné.
  • Slouží type pro typ obsahu zprávy, například Text nebo Html. Pokud není zadaný, nastaví se text.
  • Slouží senderDisplayName k zadání zobrazovaného jména odesílatele. Pokud není zadaný, nastaví se prázdný řetězec.
  • Volitelně můžete metadata zahrnout všechna další data, která chcete spolu se zprávou odeslat. Toto pole poskytuje vývojářům mechanismus pro rozšíření funkčnosti chatových zpráv a přidání vlastních informací pro váš případ použití. Například při sdílení odkazu na soubor ve zprávě můžete do metadat přidat "hasAttachment:true", aby aplikace příjemce mohla odpovídajícím způsobem parsovat a zobrazit.
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;

Příjem zpráv chatu z vlákna chatu

Chatové zprávy můžete načíst dotazováním GetMessages metody v klientovi vlákna chatu v zadaných intervalech.

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

GetMessages přebírá volitelný DateTimeOffset parametr. Pokud je zadaný posun, obdržíte po něm přijaté, aktualizované nebo odstraněné zprávy. Všimněte si, že zprávy přijaté před posunem času, ale upraveny nebo odebrané po vrácení budou také vráceny.

GetMessages vrátí nejnovější verzi zprávy, včetně všech úprav nebo odstranění, které se stalo se zprávou pomocí UpdateMessage a DeleteMessage. U odstraněných zpráv chatMessage.DeletedOn vrátí hodnotu datetime označující, kdy byla tato zpráva odstraněna. U upravených zpráv vrátí datum a čas označující chatMessage.EditedOn , kdy byla zpráva upravena. K původnímu času vytvoření zprávy lze přistupovat pomocí chatMessage.CreatedOna lze ho použít k řazení zpráv.

GetMessages vrací různé typy zpráv, které lze identifikovat chatMessage.Typepomocí funkce . Mezi tyto typy patří:

  • Text: Běžná chatovací zpráva odeslaná členem vlákna.

  • Html: Formátovaná textová zpráva. Všimněte si, že uživatelé komunikačních služeb momentálně nemůžou posílat zprávy RichText. Tento typ zprávy podporuje zprávy odesílané uživateli Teams do komunikačních služeb ve scénářích interoperability Teams.

  • TopicUpdated: Systémová zpráva, která označuje, že téma bylo aktualizováno. (jen pro čtení)

  • ParticipantAdded: Systémová zpráva, která indikuje, že jeden nebo více účastníků bylo přidáno do vlákna chatu. (jen pro čtení)

  • ParticipantRemoved: Systémová zpráva, která indikuje, že účastník byl odebrán z vlákna chatu.

Další podrobnosti najdete v tématu Typy zpráv.

Přidání uživatele jako účastníka do vlákna chatu

Po vytvoření vlákna z něj můžete přidat a odebrat uživatele. Přidáním uživatelů jim udělíte přístup, aby mohli odesílat zprávy do vlákna a přidávat nebo odebírat další účastníky. Před voláním AddParticipantsse ujistěte, že jste získali nový přístupový token a identitu pro daného uživatele. Uživatel bude tento přístupový token potřebovat k inicializaci svého chatovacího klienta.

Slouží AddParticipants k přidání jednoho nebo více účastníků do vlákna chatu. Následující atributy jsou podporované pro všechny účastníky vlákna:

  • communicationUser, povinné, je identita účastníka vlákna.
  • displayName, volitelné, je zobrazovaný název účastníka vlákna.
  • shareHistoryTime, nepovinný čas, ze kterého se historie chatu sdílí s účastníkem.
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);

Získání účastníků vlákna

Umožňuje GetParticipants načíst účastníky vlákna chatu.

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

Odeslat potvrzení o přečtení

Slouží SendReadReceipt k upozorňovat ostatní účastníky, že uživatel zprávu přečte.

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

Spuštění kódu

Spusťte aplikaci z adresáře aplikace pomocí dotnet run příkazu.

dotnet run

Ukázka kódu

Najděte finalizovaný kód pro tento rychlý start na GitHubu.

Předpoklady

Než začnete, nezapomeňte:

  • Vytvořte účet Azure s aktivním předplatným. Podrobnosti najdete v tématu Vytvoření účtu zdarma.

  • Nainstalujte Xcode a CocoaPods. Pomocí Xcode vytvoříte aplikaci pro iOS pro rychlý start a CocoaPods k instalaci závislostí.

  • Vytvořte zdroj Azure Communication Services. Podrobnosti najdete v tématu Rychlý start: Vytvoření a správa prostředků komunikačních služeb. Pro účely tohoto rychlého startu budete muset zaznamenat koncový bod prostředku a připojovací řetězec.

  • Vytvořte dva uživatele ve službě Azure Communication Services a zadejte jim přístupový token uživatele. Nezapomeňte nastavit obor pro chat a poznamenejte si řetězec tokenu i řetězec user_id. V tomto rychlém startu vytvoříte vlákno s počátečním účastníkem a pak do vlákna přidáte druhého účastníka. K vytvoření uživatele a přístupového tokenu můžete také použít Azure CLI a spustit následující příkaz s připojovací řetězec.

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

    Podrobnosti najdete v tématu Použití Azure CLI k vytváření a správě přístupových tokenů.

Nastavení

Vytvoření nové aplikace pro iOS

Otevřete Xcode a vyberte Vytvořit nový projekt Xcode. Pak jako platformu a aplikaci pro šablonu vyberte iOS.

Jako název projektu zadejte ChatQuickstart. Pak jako rozhraní vyberte Storyboard , jako životní cyklus delegáta aplikace UIKit a jako jazyk Swift .

Vyberte Další a zvolte adresář, ve kterém má být projekt vytvořen.

Instalace knihoven

Pomocí CocoaPods nainstalujte potřebné závislosti komunikačních služeb.

Z příkazového řádku přejděte do kořenového ChatQuickstart adresáře projektu iOS. Vytvořte podfile pomocí následujícího příkazu: pod init.

Otevřete soubor Podfile a přidejte do ChatQuickstart cíle následující závislosti:

pod 'AzureCommunicationChat', '~> 1.3.4'

Nainstalujte závislosti pomocí následujícího příkazu: pod install. Všimněte si, že se tím také vytvoří pracovní prostor Xcode.

Po spuštění pod installznovu otevřete projekt v Xcode výběrem nově vytvořeného .xcworkspacesouboru .

Nastavení zástupných symbolů

Otevřete pracovní prostor ChatQuickstart.xcworkspace v Xcode a pak otevřete ViewController.swift.

V tomto rychlém startu přidáte kód do viewControllerkonzoly Xcode a zobrazíte výstup. Tento rychlý start neřeší sestavení uživatelského rozhraní v iOSu.

V horní části viewController.swiftstránky naimportujte knihovnyAzureCommunication:AzureCommunicatonChat

import AzureCommunicationCommon
import AzureCommunicationChat

Zkopírujte následující kód do viewDidLoad() metody 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)")
            }
        }
    }

Pro demonstrační účely použijeme k synchronizaci kódu semafor. V následujících krocích nahradíte zástupné symboly vzorovým kódem pomocí knihovny chatu služby Azure Communication Services.

Vytvoření chatovacího klienta

K vytvoření chatovacího klienta použijete koncový bod komunikační služby a přístupový token, který se vygeneroval v rámci kroků požadavků.

Přečtěte si další informace o tokenech přístupu uživatelů.

Tento rychlý start nepokrývá vytvoření úrovně služby pro správu tokenů pro chatovací aplikaci, i když se doporučuje. Další informace o architektuře chatu

Nahraďte komentář <CREATE A CHAT CLIENT> následujícím fragmentem kódu:

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
)

Nahraďte <ACS_RESOURCE_ENDPOINT> koncovým bodem vašeho prostředku Azure Communication Services. Nahraďte <ACCESS_TOKEN> platným přístupovým tokenem komunikační služby.

Objektový model

Následující třídy a rozhraní zpracovávají některé z hlavních funkcí sady SDK chatu služby Azure Communication Services pro iOS.

Název Popis
ChatClient Tato třída je potřebná pro funkci chatu. Vytvoříte instanci s informacemi o předplatném a použijete je k vytvoření, získání, odstranění vláken a přihlášení k odběru událostí chatu.
ChatThreadClient Tato třída je potřebná pro funkci vlákna chatu. Instanci získáte prostřednictvím ChatClienta použijete ji k odesílání, přijímání, aktualizaci a odstraňování zpráv. Můžete ho také použít k přidávání, odebírání a získávání uživatelů, odesílání oznámení o psaní a potvrzení o přečtení.

Zahájení vlákna chatu

CreateChatThreadResult je odpověď vrácená z vytvoření vlákna chatu. Obsahuje chatThread vlastnost, která je objektem ChatThreadProperties . Tento objekt obsahuje threadId, které lze použít k získání operací s vytvořeným vláknem ChatThreadClient : přidání účastníků, odeslání zprávy atd.

Nahraďte komentář <CREATE A CHAT THREAD> následujícím fragmentem kódu:

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()

Nahraďte <USER_ID> platným ID uživatele služby Communication Services.

Tady používáte semaphore, abyste před pokračováním čekali na obslužnou rutinu dokončení. V pozdějších krocích použijete threadId odpověď vrácenou obslužné rutině dokončení.

Zobrazení seznamu všech vláken chatu

Po vytvoření vlákna chatu můžeme vypsat všechna vlákna chatu voláním listChatThreads metody on ChatClient. Nahraďte komentář <LIST ALL CHAT THREADS> následujícím kódem:

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()

Získání klienta vlákna chatu

Metoda createClient vrátí ChatThreadClient pro vlákno, které již existuje. Dá se použít k provádění operací ve vytvořeném vlákně: přidání účastníků, odeslání zprávy atd. threadId je jedinečné ID existujícího vlákna chatu.

Nahraďte komentář <GET A CHAT THREAD CLIENT> následujícím kódem:

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

Odeslání zprávy do vlákna chatu

send Pomocí metody odešlete zprávu do vlákna identifikovaného threadId.

SendChatMessageRequest slouží k popisu žádosti o zprávu:

  • Slouží content k poskytnutí obsahu zprávy chatu.
  • Slouží senderDisplayName k zadání zobrazovaného jména odesílatele.
  • Slouží type k určení typu zprávy, například "text" nebo "html".
  • Volitelně můžete metadata zahrnout všechna další data, která chcete spolu se zprávou odeslat. Toto pole poskytuje vývojářům mechanismus pro rozšíření funkčnosti chatových zpráv a přidání vlastních informací pro váš případ použití. Například při sdílení odkazu na soubor ve zprávě můžete do metadat přidat "hasAttachment:true", aby aplikace příjemce mohla odpovídajícím způsobem parsovat a zobrazit.

SendChatMessageResult je odpověď vrácená odesláním zprávy, obsahuje ID, což je jedinečné ID zprávy.

Nahraďte komentář <SEND A MESSAGE> následujícím fragmentem kódu:

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()

Odeslání potvrzení o přečtení

sendReadReceipt Metoda slouží k publikování události potvrzení o přečtení do vlákna chatu jménem uživatele. messageId je jedinečné ID přečtené zprávy chatu.

Nahraďte komentář <SEND A READ RECEIPT> následujícím kódem:

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")
}

Příjem zpráv chatu z vlákna chatu

Díky signalizaci v reálném čase se můžete přihlásit k odběru nových příchozích zpráv a odpovídajícím způsobem aktualizovat aktuální zprávy v paměti. Azure Communication Services podporuje seznam událostí, ke kterým se můžete přihlásit.

Nahraďte komentář <RECEIVE MESSAGES> následujícím kódem. Po povolení oznámení zkuste odeslat nové zprávy, abyste viděli 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
    }
})

Případně můžete načíst chatové zprávy dotazováním listMessages metody v zadaných intervalech. Podívejte se na následující fragment kódu pro 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()

Přidání uživatele jako účastníka do vlákna chatu

Po vytvoření vlákna z něj můžete přidat a odebrat uživatele. Přidáním uživatelů jim udělíte přístup, aby mohli odesílat zprávy do vlákna a přidávat nebo odebírat další účastníky. Před voláním addse ujistěte, že jste získali nový přístupový token a identitu pro daného uživatele. Uživatel bude tento přístupový token potřebovat k inicializaci svého chatovacího klienta.

Použijte metodu addChatThreadClient přidání jednoho nebo více účastníků do vlákna chatu. Následující atributy jsou podporované pro všechny účastníky vlákna:

  • id, povinné, je identita účastníka vlákna.
  • displayName, volitelné, je zobrazovaný název účastníka vlákna.
  • shareHistoryTime, nepovinný čas, ze kterého se historie chatu sdílí s účastníkem.

Nahraďte komentář <ADD A USER> následujícím kódem:

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()

Nahraďte <USER_ID> ID uživatele komunikační služby, které se má přidat.

Zobrazení seznamu uživatelů ve vlákně

listParticipants Pomocí této metody můžete získat všechny účastníky pro konkrétní vlákno chatu.

Nahraďte komentář <LIST USERS> následujícím kódem:

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()

Nabízená oznámení

Nabízená oznámení informují klienty o příchozích zprávách ve vlákně chatu v situacích, kdy mobilní aplikace není spuštěná v popředí. Aktuálně odesílání nabízených oznámení chatu pomocí Centra oznámení je podporováno pro IOS SDK ve verzi 1.3.0. Podrobnosti najdete v článku Povolení nabízených oznámení v chatovací aplikaci .

Spuštění kódu

V Xcode stiskněte tlačítko Spustit a sestavte a spusťte projekt. V konzole můžete zobrazit výstup z kódu a výstup protokolovacího modulu z ChatClient.

Poznámka: Nastaveno Build Settings > Build Options > Enable Bitcode na Nohodnotu . V současné době sada SDK AzureCommunicationChat pro iOS nepodporuje povolení bitcode, následující problém GitHubu to sleduje.

Ukázka kódu

Najděte finalizovaný kód pro tento rychlý start na GitHubu.

Předpoklady

Vytvořit uživatele

Proveďte tyto kroky v Power Automate s tokem Power Automate otevřeným v režimu úprav.

Přidání nového kroku v pracovním postupu pomocí konektoru identity komunikační služby:

  1. V návrháři v kroku, do kterého chcete přidat novou akci, vyberte Nový krok. Pokud chcete také přidat novou akci mezi kroky, přesuňte ukazatel myši na šipku mezi těmito kroky, vyberte znaménko plus (+) a pak vyberte Přidat akci.

  2. Do vyhledávacího pole Zvolit operaci zadejte identitu komunikační služby. V seznamu akcí vyberte Vytvořit uživatele.

    Screenshot that shows the Azure Communication Services Identity connector Create user action.

  3. Zadejte připojovací řetězec. Pokud chcete získat adresu URL připojovací řetězec na webu Azure Portal, přejděte k prostředku Azure Communication Services. V nabídce prostředků vyberte Klíče a pak vyberte Připojení řetězec. Výběrem ikony kopírování zkopírujte připojovací řetězec.

    Screenshot that shows the Keys pane for an Azure Communication Services resource.

  4. Zadejte název připojení.

  5. Vyberte Zobrazit upřesňující možnosti a pak vyberte obor tokenu. Akce vygeneruje přístupový token a čas vypršení platnosti se zadaným oborem. Tato akce také vygeneruje ID uživatele, které je identitou uživatele komunikační služby.

    Screenshot that shows the Azure Communication Services Identity connector Create user action options.

  6. V položce Obory tokenů vyberte chat.

    Screenshot that shows the Azure Communication Services Chat connector advanced options.

  7. Vyberte Vytvořit. Zobrazí se ID uživatele a přístupový token.

Vytvoření vlákna chatu

  1. Přidejte novou akci.

  2. Do vyhledávacího pole Zvolit operaci zadejte Chat komunikačních služeb. V seznamu akcí vyberte Vytvořit vlákno chatu.

    Screenshot that shows the Azure Communication Services Chat connector Create a chat thread action.

  3. Zadejte adresu URL koncového bodu komunikační služby. Pokud chcete získat adresu URL koncového bodu na webu Azure Portal, přejděte k prostředku Azure Communication Services. V nabídce prostředků vyberte Klíče a pak vyberte Koncový bod.

  4. Zadejte název připojení.

  5. Vyberte přístupový token vygenerovaný v předchozí části a přidejte popis tématu vlákna chatu. Přidejte vytvořeného uživatele a zadejte jméno účastníka.

    Screenshot that shows the Azure Communication Services Chat connector Create chat thread action dialog.

Odeslání zprávy

  1. Přidejte novou akci.

  2. Do vyhledávacího pole Zvolit operaci zadejte Chat komunikačních služeb. V seznamu akcí vyberte Odeslat zprávu do vlákna chatu.

    Screenshot that shows the Azure Communication Services Chat connector Send chat message action.

  3. Zadejte přístupový token, ID vlákna, obsah a název.

    Screenshot that shows the Azure Communication Services Chat connector Send chat message action dialog.

Výpis zpráv vlákna chatu

Ověření, že jste zprávu odeslali správně:

  1. Přidejte novou akci.

  2. Do vyhledávacího pole Zvolit operaci zadejte Chat komunikačních služeb. V seznamu akcí vyberte Vypsat zprávy vlákna chatu.

    Screenshot that shows the Azure Communication Services Chat connector List chat messages action.

  3. Zadejte přístupový token a ID vlákna.

    Screenshot that shows the Azure Communication Services Chat connector List chat messages action dialog.

Testování aplikace logiky

Pokud chcete pracovní postup spustit ručně, vyberte na panelu nástrojů návrháře možnost Spustit. Pracovní postup vytvoří uživatele, vydá přístupový token pro daného uživatele a pak token odebere a odstraní uživatele. Další informace najdete v tématu Postup spuštění pracovního postupu.

Teď vyberte Seznam zpráv vlákna chatu. Ve výstupech akce zkontrolujte zprávu, která byla odeslána.

Screenshot that shows the Azure Communication Services Chat connector Send chat message action results.

Vyčištění prostředků pracovního postupu

Pokud chcete vyčistit pracovní postup aplikace logiky a související prostředky, přečtěte si , jak vyčistit prostředky Logic Apps.

Vyčištění prostředků

Pokud chcete vyčistit a odebrat předplatné služby Communication Services, můžete odstranit prostředek nebo skupinu prostředků. Odstraněním skupiny prostředků se odstraní také všechny ostatní prostředky, které jsou k ní přidružené. Přečtěte si další informace o čištění prostředků.

Další kroky

V tomto rychlém startu jste se naučili:

  • Vytvoření chatovacího klienta
  • Vytvoření vlákna se dvěma uživateli
  • Odeslání zprávy do vlákna
  • Příjem zpráv z vlákna
  • Odebrání uživatelů z vlákna

Vyzkoušení aplikace Chat Hero

Můžete také chtít: