Přidání chatu do aplikace

Přidejte do aplikace chat v reálném čase pomocí sady SDK chatu komunikačních služeb. Tento článek popisuje, jak pomocí sady SDK chatu vytvářet vlákna chatu, která uživatelům umožňují vzájemně komunikovat. Další informace si o konceptech zjistíte v konceptuální 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ích služeb.

  • Nainstalujte Azure CLI.

  • Poznamenejte si koncový bod prostředku komunikační služby. Koncový bod můžete získat z webu Azure Portal. Případně lze adresu URL koncového bodu najít v připojovacím řetězci. 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, a také ř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 vaším připojovacím řetězcem.

    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

Musíte se přihlásit k Azure CLI. Můžete se přihlásit spuštěním az login příkazu z terminálu a zadáním přihlašovacích údajů.

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

Uložte koncový bod do proměnné prostředí

Proměnnou prostředí AZURE_COMMUNICATION_ENDPOINT můžete nakonfigurovat k používání operací chatu Azure CLI, aniž byste museli zadávat koncový bod --endpoint. 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á budete muset restartovat všechny spuštěné programy, které potřebují přečíst proměnnou prostředí, 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žte přístupový token 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á budete muset restartovat všechny spuštěné programy, které potřebují přečíst proměnnou prostředí, 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 bylo uvedeno dříve, nemusíte je předávat do příkazu.

az communication chat thread create --topic "<chatTopic>"
  • Použijte <chatTopic>, abyste dali vláknu téma. 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é: Slouží <startTime> k určení nejstaršího bodu v čase pro získání zpráv 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.
  • Můžete volitelně <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 zadat <startTime>, abyste určili nejstarší bod v čase pro přijímání chatových zpráv.
  • 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> za 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.
  • Můžete volitelně <displayName> zadat zobrazované jméno odesílatele.
  • Volitelně můžete zadat <startTime>, abyste určili nejstarší bod v čase pro přijímání chatových zpráv.
  • 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í příkazu participant list 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.
  • Můžete volitelně použít <skip> k přeskočení účastníků až 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.

Požadavky

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

  • Nainstalujte verze 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. Musíte zaznamenat koncový bod prostředku a připojovací řetězec v rámci tohoto článku.

  • 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, a také ř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 vaším připojovacím řetězcem.

    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 uvede knihovnu jako závislost v package.json.

Nastavení architektury aplikace

Tento článek používá webpack ke sloučení prostředků aplikace. Spuštěním následujícího příkazu ho nainstalujte a vypište ji jako vývojovou závislost ve vašem package.json:

npm install webpack webpack-cli webpack-dev-server --save-dev

V kořenovém adresáři projektu vytvořte webpack.config.js .

module.exports = {
    entry: "./client.js",
    output: {
        filename: "bundle.js"
    },
    devtool: "inline-source-map",
    mode: "development"
}

V kořenovém adresáři projektu vytvořte soubor index.html . Tento soubor můžete použít jako šablonu k přidání funkce chatu pomocí sady SDK komunikačního chatu Azure 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="./bundle.js"></script>
  </body>
</html>

V kořenovém adresáři projektu vytvořte soubor s názvemclient.js , který bude obsahovat logiku aplikace pro tento článek.

Vytvoření chatovacího klienta

K vytvoření chatovacího klienta ve webové aplikaci použijte 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 článek se nezabývá vytvořením úrovně služby pro správu tokenů pro chatovací aplikaci. Další informace o architektuře chatu najdete v tématu Koncepty chatu. Další informace o přístupových tokenech najdete v tématu Přístupové tokeny uživatele.

Uvnitř client.js použijte koncový bod a přístupový token v následujícím kódu k přidání chatu pomocí sady SDK pro 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!');

Spuštění kódu

scripts Aktualizujte oddíl v package.json tak, aby zahrnoval "start".

"start": "webpack serve --config ./webpack.config.js"

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

npm install
npm run start

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

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í metoda createChatThread vrátí CreateChatThreadResult. Tento model obsahuje vlastnost chatThread, pomocí které máte přístup k id nově vytvořeného vlákna. 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ž obnovíte kartu prohlížeče, měla by se v konzole zobrazit následující zpráva:

Thread created: <thread_id>

Získejte klienta pro vlákno 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 o typu 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

Použijte metodu sendMessage k odeslání zprávy do vlákna určeného 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 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
});

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

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


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

Místo komentáře do <LIST MESSAGES IN A CHAT THREAD> přidejte tento kód. 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 pomocí chatMessage.type.

Další informace naleznete 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 získali nový přístupový token a identitu pro daného uživatele. Aby mohl uživatel inicializovat svého chatovacího klienta, potřebuje tento přístupový token.

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 nechcete sdílet žádnou historii před přidáním úč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_ID novým ID uživatele. Přidejte tento kód místo komentáře <ADD NEW PARTICIPANT TO THREAD> 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, musíte 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>). Místo komentáře do <REMOVE PARTICIPANT FROM THREAD> přidejte tento kód.

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ázkový kód

Najděte finalizovaný kód pro tento článek v ukázce Přidání chatu do aplikace na GitHubu.

Požadavky

  • 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. Musíte zaznamenat koncový bod prostředku a připojovací řetězec v rámci tohoto článku.

  • Přístupový token uživatele. Nezapomeňte nastavit obor pro chat a poznamenejte si řetězec tokenu, a také ř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 vaším připojovacím řetězcem.

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

Instalace

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řidejte do tohoto souboru veškerý zdrojový kód pro tento článek.

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í o psaní 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 článek se nezabývá vytvořením úrovně služby pro správu tokenů pro chatovací aplikaci, ale doporučuje se. Další informace najdete v části "Architektura chatu" v sekci Chatové koncepty>.

Zahájení vlákna chatu

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

  • Použijte topic, abyste dali vláknu téma. Téma můžete aktualizovat po vytvoření vlákna chatu update_thread pomocí funkce.
  • Pomocí thread_participants vypsat ChatParticipant k přidání do vlákna chatu. ChatParticipant používá typ 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. Tohle id lze použít k načtení objektu ChatThreadClient pomocí metody get_chat_thread_client. Můžete použít ChatThreadClient, abyste provedli další operace v tomto vlákně 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ískejte klienta pro vlákno 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.

Můžete použít ChatThreadClient, abyste provedli další operace v tomto vlákně 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

Pomocí metody send_message odešlete zprávu do vlákna chatu, které jste vytvořili a které je identifikované pomocí 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.

  • Pomocí results_per_page určete maximální počet zpráv, které budou zobrazeny na stránce.
  • Použijte 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 vrátí různé typy zpráv, které identifikujete z 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.

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

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

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

  • Pomocí results_per_page určete maximální počet účastníků, kteří se mají zobrazit na stránku.
  • Použijte skip k přeskočení účastníků až do zadané pozice 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ázkový kód

Najděte finalizovaný kód pro tento článek v ukázce Přidání chatu do aplikace 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 maven-archetype-quickstart šablony.

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

Cílem generate je vytvořit 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 zdroj testu a pom.xml soubor 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řidejte odkazy na balíčky pro SDK pro chat

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žijte 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 App.java souboru, 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.

  • Použijte parametr topic konstruktoru k přiřazení tématu tomuto chatu; Téma lze aktualizovat po vytvoření vlákna chatu pomocí funkce UpdateThread.
  • Slouží participants k zobrazení seznamu účastníků vlákna, které se mají přidat do vlákna. ChatParticipant převezme uživatele, který jste vytvořili v přístupovém tokenu 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ískejte klienta pro vlákno 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 nebo TEXTHTML.
  • 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

Načíst chatové zprávy lze voláním metody listMessages na 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

Použijte listParticipants k načtení stránkované kolekce obsahující účastníky vlákna chatu identifikovaného chatThreadId.

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

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

  • communicationIdentifier, povinné, je CommunicationIdentifier, který jste vytvořili pomocí CommunicationIdentityClient v 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 nechcete sdílet žádnou historii před přidáním úč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 pom.xml příkazu přejděte do adresáře obsahujícího mvn soubor 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ázkový kód

Najděte finalizovaný kód pro tento článek v ukázce Přidání chatu do aplikace na GitHubu.

Požadavky

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

  • Nainstalujte Android Studio, používáme Android Studio k vytvoření aplikace pro Android a k instalaci závislostí.

  • Vytvořte zdroj Azure Communication Services. Podrobnosti najdete v tématu Vytvoření prostředku Azure Communication Services. Musíte zaznamenat koncový bod prostředku a připojovací řetězec v rámci tohoto článku.

  • Vytvořte dva uživatele komunikačních služeb a vydáte jim přístupový token uživatele. Nezapomeňte nastavit obor na chat a poznamenejte si řetězec tokenu a uživatelské ID. V tomto článku vytvoříme vlákno s počátečním účastníkem a pak do vlákna přidáme 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 vaším připojovacím řetězcem.

    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 Android

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

Instalace knihoven

Gradle používáme k instalaci potřebných závislostí komunikačních služeb. 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 libs.azure.communication.common
implementation libs.azure.communication.chat
implementation libs.slf4j.log4j12

Nejnovější čísla verzí najdete v části https://search.maven.org/artifact/com.azure.android/azure-communication-common a https://search.maven.org/artifact/com.azure.android/azure-communication-chat.

Vyloučit meta soubory v možnostech balení v kořenovém souboru 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 tématu Integrace funkce Azure Functions. 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 článku přidáme náš kód do MainActivitya zobrazíme výstup v konzole. Tento článek 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) {
        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 do MainActivity.java, pokud je splněna kterákoliv 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. Jinak si přečtěte krok 11 v nabízených oznámeních androidu. Referenční informace najdete v ukázkové aplikaci verze sady SDK, kterou používáte.

ACS_ENDPOINT, FIRST_USER_ID a FIRST_USER_ACCESS_TOKEN se vrací z volání funkce Azure. Další informace najdete v tématu Integrace 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 inicializaci 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

Pomocí našeho ChatAsyncClient příkazu vytvořte nové vlákno 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ískejte klienta pro vlákno chatu

Jakmile jsme vytvořili vlákno chatu, potřebujeme získat ChatThreadAsyncClient, abychom mohli provádět operace 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

Odešlete zprávu do vlákna chatu.

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: Pokud používáte sadu SDK pro chat a volání androidu společně ve stejné aplikaci, funkce oznámení sady Chat SDK v reálném čase nefunguje. Může se stát, že nastane problém s řešením závislostí. Funkci oznámení v reálném čase můžete vypnout tak, že do souboru aplikace build.gradle přidáte následující informace o závislostech a namísto toho pravidelně dotazujete API GetMessages, abyste uživatelům zobrazili 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'

Vezměte na vědomí, že s touto aktualizací, pokud se aplikace pokusí kontaktovat rozhraní API pro oznámení pomocí chatAsyncClient.startRealtimeNotifications() nebo chatAsyncClient.addEventHandler(), vygeneruje chybu za běhu.

Nabízená oznámení

Další informace najdete v tématu Nabízená oznámení pro Android.

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

Odeberte druhého uživatele z vlákna.

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í oznámení o psaní

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

chatThreadAsyncClient.sendTypingNotification().get();

Odeslat potvrzení o přečtení

Odešleme potvrzení o přečtení pro dříve odeslanou zprávu.

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ázkový kód

Najděte finalizovaný kód pro tento článek v ukázce Přidání chatu do aplikace na GitHubu.

Požadavky

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žijte koncový bod komunikační služby a přístupový token, který se vygeneroval v rámci požadovaných kroků. 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 článek se nezabývá vytvořením úrovně služby pro správu tokenů pro chatovací aplikaci, i když ji doporučujeme. Další informace najdete v tématu Architektura chatu.

Zkopírujte následující fragmenty kódu a vložte je do zdrojového Program.cs souboru.

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 pro tento chat. Téma můžete 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, MicrosoftTeamsUserIdentifiernebo PhoneNumberIdentifier. Pokud například chcete získat CommunicationIdentifier objekt, musíte 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 ChatClient klientovi.

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ískejte klienta pro vlákno chatu

Metoda GetChatThreadClient 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ě: 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. Povinné.
  • Slouží type pro typ obsahu zprávy, například Text nebo Html. Pokud není zadaný, je nastaven text.
  • Slouží senderDisplayName k zadání zobrazovaného jména odesílatele. Pokud není zadaný, nastaví se prázdný řetězec.
  • Volitelné: Slouží metadata k zahrnutí dalších dat, 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

Načíst chatové zprávy lze voláním metody GetMessages na 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ý offset, obdržíte zprávy, které byly po tomto bodě přijaty, aktualizovány nebo odstraněny. Zprávy přijaté před posunem času, ale upravované nebo odebrané poté se vrátí také.

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 vrátí různé typy zpráv. Typ můžete identifikovat v sadě chatMessage.Type. Typy jsou:

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

  • Html: Formátovaná textová zpráva. Uživatelé komunikačních služeb momentálně nemůžou posílat zprávy RichText. Tento typ zprávy se podporuje u zpráv odesílaných uživateli Teams do komunikačních služeb ve scénářích spolupráce Teams.

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

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

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

Další informace naleznete 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 pro daného uživatele získáte nový přístupový token a identitu. Aby mohl uživatel inicializovat svého chatovacího klienta, potřebuje tento přístupový token.

Slouží AddParticipants k přidání jednoho nebo více účastníků do vlákna chatu. Následující atributy jsou podporované pro každého účastníka 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

Použijte GetParticipants k načtení účastníků 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í

Použijte SendReadReceipt k upozornění ostatních účastníků, že uživatel zprávu přečetl.

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 článek v ukázce Přidání chatu do aplikace na GitHubu.

Požadavky

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

  • Nainstalujte Xcode a CocoaPods. Xcode slouží k vytvoření aplikace pro iOS pro tento článek 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. Musíte zaznamenat koncový bod prostředku a připojovací řetězec v rámci tohoto článku.

  • 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, a také řetězec user_id. V tomto článku 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 vaším připojovacím řetězcem.

    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 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.6'

Nainstalujte závislosti pomocí následujícího příkazu: pod install. Tím se vytvoří také pracovní prostor Xcode.

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

Nastavení zástupných symbolů

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

V tomto článku přidáte kód do viewControllerkonzoly Xcode a zobrazíte výstup. Tento článek se nezabývá sestavením uživatelského rozhraní v iOSu.

Na začátku viewController.swift naimportujte knihovny AzureCommunication a AzureCommunicationChat.

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žíváme 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žijte koncový bod komunikační služby a přístupový token, který se vygeneroval v rámci požadovaných kroků.

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

Tento článek se nezabývá vytvořením úrovně služby pro správu tokenů pro chatovací aplikaci, ale doporučujeme ji. 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 vyhledá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í ChatThreadClient, který umožňuje provádět operace s vytvořeným vláknem: 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.

Používáte zde semafor, abyste čekali na dokončovací obslužnou rutinu před pokračováním. V pozdějších krocích použijte threadId odpověď vrácenou do obslužné rutiny 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 metody listChatThreads na 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ískejte klienta pro vlákno 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()

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. 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 chatové zprávy načíst dotazováním metody listMessages 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 potřebuje přístupový token, aby mohl inicializovat svého chatovacího klienta.

Použijte metodu add od ChatThreadClient k přidání jednoho nebo více účastníků do vlákna chatu. Následující atributy jsou podporované pro každého účastníka 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í upozorňují klienty na příchozí zprávy v chatovacím vlákně v situacích, kdy mobilní aplikace není spuštěná v popředí.

V současné době se podpora odesílání chatových push oznámení pomocí Notification Hub vztahuje na iOS SDK verze 1.3.0.

Další informace najdete v tématu Povolení nabízených oznámení v chatovací aplikaci.

Spuštění kódu

Vypnutí sandboxu uživatelských skriptů

Některé skripty v propojených knihovnách zapisují soubory během procesu sestavení. Pokud chcete povolit zápis souborů, zakažte sandboxing uživatelských skriptů v Xcode.

V projektu Xcode v části Nastavení sestavení nastavte možnost Sandboxing uživatelského skriptu na Ne. Pokud chcete nastavení najít, změňte filtr ze Základní na Vše nebo použijte panel hledání.

Snímek obrazovky znázorňující možnost Nastavení sestavení pro vypnutí sandboxu uživatelských skriptů

Spusťte projekt

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.

Ukázkový kód

Najděte finalizovaný kód pro tento článek v ukázce Přidání chatu do aplikace na GitHubu.

Požadavky

Vytvořit uživatele

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

Chcete-li přidat nový krok do pracovního postupu pomocí konektoru identity komunikačních služeb:

  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.

    Snímek obrazovky znázorňující akci Vytvoření uživatelského konektoru identity služby Azure Communication Services

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

    Snímek obrazovky, který ukazuje podokno Klíče pro prostředek Azure Communication Services

  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.

    Snímek obrazovky znázorňující možnosti akce Vytvoření uživatele konektoru Identita služby Azure Communication Services.

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

    Snímek obrazovky s rozšířenými možnostmi konektoru chatu služby Azure Communication Services

  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 Komunikační služby Chat. V seznamu akcí vyberte Vytvořit vlákno chatu.

    Snímek obrazovky, který znázorňuje akci Vytvořit vlákno chatu konektoru Azure Communication Services Chat.

  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.

    Snímek obrazovky s dialogovým oknem pro vytvoření vlákna chatu v konektoru chatu služby Azure Communication Services

Odeslání zprávy

  1. Přidejte novou akci.

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

    Snímek obrazovky znázorňující akci odeslání chatové zprávy konektoru chatu služby Azure Communication Services

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

    Snímek obrazovky s dialogovým oknem akce Odeslat zprávu chatu v konektoru chatu služby Azure Communication Services

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 Komunikační služby Chat. V seznamu akcí vyberte Vypsat zprávy z vlákna chatu.

    Snímek obrazovky znázorňující akci seznamu chatových zpráv v chatu konektoru služby Azure Communication Services.

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

    Snímek obrazovky znázorňující dialogové okno akce Seznam zpráv chatu v konektoru chatu služby Azure Communication Services

Testování aplikace logiky

Pokud chcete pracovní postup spustit ručně, vyberte na panelu nástrojů návrháře 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 naleznete v tématu Jak spustit pracovní postup.

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

Snímek obrazovky znázorňující výsledky akce chatu v konektoru Chat služby Azure Communication Services

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é komunikačních služeb, 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é. Další informace najdete v tématu Čištění prostředků.

Další kroky

Tento článek popisuje, jak:

  • 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

  • Last updated on