Краткое руководство. Добавление чата в приложение

  • Статья

Начало работы со Службами коммуникации Azure с помощью пакета SDK для чата Служб коммуникации для добавления в приложение чата с поддержкой реального времени. В этом кратком руководстве показано, как использовать пакет SDK для чата, чтобы создавать цепочки чатов, с помощью которых пользователи смогут общаться между собой. См. сведения о чатах в документации.

Необходимые компоненты

  • Учетная запись Azure с активной подпиской. Создайте учетную запись бесплатно .

  • Активный ресурс Служб коммуникации и строка подключения. Создайте ресурс Служб коммуникации.

  • Установите Azure CLI.

  • Обратите внимание на конечную точку ресурса Служб коммуникации. Конечную точку можно получить из портал Azure. Кроме того, можно найти URL-адрес конечной точки в строка подключения. Это URL-адрес, который приходит после endpoint= и начинается с https://.

  • Маркер доступа пользователя. Не забудьте задать область чата и запишите строку токена, а также строку user_id. Вы также можете использовать Azure CLI и выполнить приведенную ниже команду с помощью строка подключения для создания пользователя и маркера доступа.

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

    Дополнительные сведения см. в статье "Создание маркеров доступа и управление ими" с помощью Azure CLI.

Установка

Добавление расширения

Добавьте расширение Службы коммуникации Azure для Azure CLI с помощью az extension команды.

az extension add --name communication

Вход в Azure CLI

Вам потребуется войти в Azure CLI. Вы можете выполнить команду из az login терминала и предоставить учетные данные.

(Необязательно) Использование операций идентификации Azure CLI без передачи конечной точки или маркера доступа

Хранение конечной точки в переменной среды

Вы можете настроить AZURE_COMMUNICATION_ENDPOINT переменную среды для использования операций чата Azure CLI без необходимости --endpoint передавать в конечную точку. Чтобы настроить переменную среды, откройте окно консоли и выберите операционную систему на следующих вкладках. Замените <yourEndpoint> фактической конечной точкой.

Откройте окно консоли и введите следующую команду:

setx AZURE_COMMUNICATION_ENDPOINT "<yourEndpoint>"

После добавления переменной среды может потребоваться перезапустить все запущенные приложения, которым может понадобиться считать переменную среды, в том числе окно консоли. Например, если вы используете Visual Studio в качестве редактора, перезапустите Visual Studio перед запуском примера.

Хранение маркера доступа в переменной среды

Вы можете настроить AZURE_COMMUNICATION_ACCESS_TOKEN переменную среды для использования операций чата Azure CLI без необходимости --access-token передавать маркер доступа. Чтобы настроить переменную среды, откройте окно консоли и выберите операционную систему на следующих вкладках. Замените <yourAccessToken> фактическим маркером доступа.

Откройте окно консоли и введите следующую команду:

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

После добавления переменной среды может потребоваться перезапустить все запущенные приложения, которым может понадобиться считать переменную среды, в том числе окно консоли. Например, если вы используете Visual Studio в качестве редактора, перезапустите Visual Studio перед запуском примера.

Operations

Запуск потока чата

thread create Используйте команду для создания потока чата.

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

Если вы сохранили конечную точку и маркер доступа в переменных среды, как указано выше, вам не потребуется передать их команде.

az communication chat thread create --topic "<chatTopic>"
  • Для указания темы беседы используйте <chatTopic>. Вы можете обновить раздел после создания потока чата thread update-topic с помощью команды.
  • Замените <endpoint> Службы коммуникации Azure конечной точкой.
  • Замените <token> маркер доступа, полученный ранее с помощью команды выполнения identity token issue .

Обновление темы беседы в чате

az communication chat thread update-topic --thread "<chatThreadId>" --topic "<chatTopic>" --endpoint "<endpoint>" --access-token "<token>"
  • Замените <chatThreadId> идентификатором потока чата.
  • Замените <chatTopic> новым разделом чата, который вы хотите задать.
  • Замените <endpoint> Службы коммуникации Azure конечной точкой.
  • Замените <token> маркер доступа, полученный ранее с помощью команды выполнения identity token issue .

Перечисление всех потоков чата

Команда thread list возвращает список потоков чата пользователя.

az communication chat thread list --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Используйте <startTime> необязательно, чтобы указать самый ранний момент времени для получения сообщений чата.
  • Замените <endpoint> Службы коммуникации Azure конечной точкой.
  • Замените <token> маркер доступа, полученный ранее с помощью команды выполнения identity token issue .

Отправка сообщения в поток чата

message send Используйте команду для отправки сообщения в созданный поток чата, определенныйthreadId.

az communication chat message send --thread "<chatThreadId>" --display-name "<displayName>" --content "<content>" --message-type "<messageType>"  --endpoint "<endpoint>" --access-token "<token>"
  • Замените <chatThreadId> идентификатором потока чата.
  • Используйте <content>, чтобы указать содержимое сообщения в чате.
  • Используйте <messageType>, чтобы указать тип содержимого сообщения. Возможные значения: text и html. Если значение не указано, по умолчанию используется text.
  • Используйте <displayName> необязательно, чтобы указать отображаемое имя отправителя.
  • Замените <endpoint> Службы коммуникации Azure конечной точкой.
  • Замените <token> маркер доступа, полученный ранее с помощью команды выполнения identity token issue .

Вывод списка сообщений чата в потоке чата

Команда message list возвращает список сообщений чата в потоке чата.

az communication chat message list --thread "<chatThreadId>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Замените <chatThreadId> идентификатором потока чата.
  • Используйте <startTime> необязательно, чтобы указать самый ранний момент времени для получения сообщений чата.
  • Замените <endpoint> Службы коммуникации Azure конечной точкой.
  • Замените <token> маркер доступа, полученный ранее с помощью команды выполнения identity token issue .

Получение сообщения чата из потока чата

Вы можете получить сообщения чата message list с помощью команды.

az communication chat message get --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Замените <chatThreadId> идентификатором потока чата.
  • Замените <messageId> идентификатором сообщения, которое требуется извлечь.
  • Замените <endpoint> Службы коммуникации Azure конечной точкой.
  • Замените <token> маркер доступа, полученный ранее с помощью команды выполнения identity token issue .

Отправка уведомления о прочтении

Вы используете message receipt send команду для публикации события квитанции для чтения в поток от имени пользователя.

az communication chat message receipt send --thread "<chatThreadId>" --message-id "<messageId>" --endpoint "<endpoint>" --access-token "<token>"
  • Замените <chatThreadId> идентификатором потока чата.
  • Замените <messageId> идентификатор последнего сообщения, прочитанного текущим пользователем.
  • Замените <endpoint> Службы коммуникации Azure конечной точкой.
  • Замените <token> маркер доступа, полученный ранее с помощью команды выполнения identity token issue .

Добавление пользователя в качестве участника в поток чата

После создания беседы чата можно добавлять и удалять пользователей. Добавляя пользователей, вы предоставляете им возможность отправлять сообщения в беседу чата, а также добавлять или удалять других участников. Перед вызовом participant add команды убедитесь, что вы приобрели новый маркер доступа и удостоверение для этого пользователя.

az communication chat participant add --thread "<chatThreadId>" --user "<userId>" --display-name "<displayName>" --start-time "<startTime>" --endpoint "<endpoint>" --access-token "<token>"
  • Замените <chatThreadId> идентификатором потока чата.
  • Замените <userId> идентификатором пользователя.
  • Используйте <displayName> необязательно, чтобы указать отображаемое имя отправителя.
  • Используйте <startTime> необязательно, чтобы указать самый ранний момент времени для получения сообщений чата.
  • Замените <endpoint> Службы коммуникации Azure конечной точкой.
  • Замените <token> маркер доступа, полученный ранее с помощью команды выполнения identity token issue .

Перечисление участников в беседе в чате

Аналогично тому, как выполняется добавление участников, вы можете перечислить их в потоке.

Используйте participant list команду для извлечения участников потока.

az communication chat participant list --thread "<chatThreadId>" --skip "<skip>" --endpoint "<endpoint>" --access-token "<token>"
  • Замените <chatThreadId> идентификатором потока чата.
  • Используйте <skip> необязательно, чтобы пропустить участников до указанной позиции в ответе.
  • Замените <endpoint> Службы коммуникации Azure конечной точкой.
  • Замените <token> маркер доступа, полученный ранее с помощью команды выполнения identity token issue .

Удаление участника из потока чата

Вы можете удалить участника чата из потока чата с помощью команды "Удалить участника".

az communication chat participant remove --thread "<chatThreadId>" --user "<userId>" --endpoint "<endpoint>" --access-token "<token>"
  • Замените <chatThreadId> идентификатором потока чата.
  • Замените <userId> идентификатор пользователя, который вы хотите удалить из потока чата.
  • Замените <endpoint> Службы коммуникации Azure конечной точкой.
  • Замените <token> маркер доступа, полученный ранее с помощью команды выполнения identity token issue .

Необходимые компоненты

Перед началом работы нужно сделать следующее:

  • Создайте учетную запись Azure с активной подпиской. Дополнительные сведения см. на странице Создайте бесплатную учетную запись Azure уже сегодня.

  • Установите Node.js (версии Active LTS и Maintenance LTS).

  • Создание ресурса Служб коммуникации Azure. Дополнительные сведения см. в кратком руководстве по созданию ресурсов Служб коммуникации и управлению ими. Для этого краткого руководства необходимо записать конечную точку ресурса и строка подключения.

  • Создайте три Службы коммуникации Azure пользователей и оставьте их маркером доступа пользователей. Не забудьте задать область чата и запишите строку токена, а также строку user_id. Полная демонстрация создает поток с двумя начальными участниками, а затем добавляет третьего участника в поток. Вы также можете использовать Azure CLI и выполнить приведенную ниже команду с помощью строка подключения для создания пользователя и маркера доступа.

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

    Дополнительные сведения см. в статье "Создание маркеров доступа и управление ими" с помощью Azure CLI.

Установка

Создание веб-приложения

Откройте терминал или командное окно, создайте каталог для своего приложения и перейдите к нему.

mkdir chat-quickstart && cd chat-quickstart

Воспользуйтесь командой npm init -y, чтобы создать файл package.json с параметрами по умолчанию.

npm init -y

Установка пакетов

Используйте команду npm install, чтобы установить указанные ниже пакеты SDK Служб коммуникации для 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

Параметр --save указывает библиотеку как зависимость в файле пакета package.json.

Настройка платформы приложения

В этом кратком руководстве используется пакет для упаковки ресурсов приложения. Выполните следующую команду, чтобы установить ее и перечислить ее в качестве зависимости разработки в файле package.json:

npm install parcel --save-dev

Создайте файл index.html в корневом каталоге проекта. Мы будем использовать этот файл в качестве шаблона для добавления возможностей чата с помощью пакета SDK чата Служб коммуникации Azure для 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>

Создайте файл в корневом каталоге проекта с именем client.js, чтобы включить логику приложения для этого краткого руководства.

Создание клиента чата

Чтобы создать клиент чата в веб-приложении, вы будете использовать конечную точку Служб коммуникации и маркер доступа, который был создан в рамках подготовки к работе.

Маркеры доступа пользователей позволяют создавать клиентские приложения, которые напрямую проходят проверку подлинности в Службах коммуникации Azure. В этом кратком руководстве не рассматривается создание уровня служб для управления маркерами для приложения чата. Дополнительные сведения об архитектуре чата и маркерах доступа пользователей см. в разделе, посвященном основным понятиям чата.

В файле client.js укажите конечную точку и маркер доступа из приведенного ниже кода, чтобы добавить возможности чата с помощью пакета SDK чата Служб коммуникации Azure для 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!');

Выполнение кода

Выполните следующую команду, чтобы запустить приложение:

npx parcel index.html

Откройте браузер и перейдите к http://localhost:1234/. В консоли средств разработчика в браузере должно отобразиться следующее:

Azure Communication Chat client created!

Объектная модель

Следующие классы и интерфейсы реализуют некоторые основные функции пакета SDK для чата Служб коммуникации для JavaScript.

Имя Описание
ChatClient Этот класс требуется для реализации всех функций чата. Его экземпляр можно создать с помощью сведений о подписке и использовать для создания, получения и удаления потоков, а также для подписки на события чата.
ChatThreadClient Этот класс требуется для реализации всех функций потоков чата. Вы получаете экземпляр с помощью ChatClient и используете его для отправки, получения, обновления и удаления сообщений, добавления, удаления и получения пользователей, а также для отправки уведомлений о вводе и уведомления о прочтении.

Запуск потока чата

Для создания потока чата используйте метод createThread.

createThreadRequest используется для описания запроса потока:

  • Используйте topic для указания темы этого чата. Тему можно обновить после создания беседы чата с помощью функции UpdateThread.
  • Используйте participants, чтобы получить список участников, добавляемых в поток чата.

При разрешении метода createChatThread возвращается CreateChatThreadResult. Эта модель содержит свойство chatThread, в котором можно получить доступ к id только что созданного потока. Затем вы можете использовать id, чтобы получить экземпляр ChatThreadClient. Затем можно использовать ChatThreadClient для выполнения операции в потоке, например при отправке сообщений или выводе списка участников.

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

При обновлении вкладки браузера вы увидите следующее в консоли:

Thread created: <thread_id>

Получение клиента потока чата

Метод getChatThreadClient возвращает chatThreadClient для потока, который уже существует. Его можно использовать для выполнения операций в созданном потоке: добавления участников, отправки сообщения и т. д. Идентификатор thread_id — это уникальный идентификатор имеющегося потока чата.

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

Добавьте этот код вместо комментария <CREATE CHAT THREAD CLIENT> в файл client.js, обновите вкладку браузера и проверьте консоль, вы увидите:

Chat Thread client for threadId: <threadId>

Перечисление всех потоков чата

Метод listChatThreads возвращает объект PagedAsyncIterableIterator типа ChatThreadItem. Его можно использовать для перечисления всех потоков чата. Итератор [ChatThreadItem] является ответом, возвращенным из списка потоков.

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

Отправка сообщения в поток чата

Используйте метод sendMessage для отправки сообщения в поток, идентифицируемый с помощью threadId.

sendMessageRequest используется для описания запроса сообщения:

  • Используйте content, чтобы указать содержимое сообщения в чате.

sendMessageOptions используется для описания необязательных параметров операции:

  • Используйте senderDisplayName, чтобы указать отображаемое имя отправителя.
  • Используется type для указания типа сообщения, например "text" или "html";
  • Используйте metadata необязательно, чтобы включить любые другие данные, которые вы хотите отправить вместе с сообщением. Это поле позволяет разработчикам расширить функциональные возможности сообщений чата и при необходимости добавить в сообщения дополнительные сведения. Например, при совместном использовании ссылки на файл в сообщении может потребоваться добавить hasAttachment: true в метаданные, чтобы приложение получателя могло проанализировать это и отобразить соответствующим образом.

SendChatMessageResult — ответ, возвращаемый при отправке сообщения. Содержит идентификатор, который является уникальным идентификатором сообщения.

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

Добавьте этот код вместо комментария <SEND MESSAGE TO A CHAT THREAD> в файл client.js, обновите вкладку браузера и проверьте консоль.

Message sent!, message id:<number>

Получение сообщений из потока чата

С помощью оповещений в реальном времени можно подписываться на прослушивание новых входящих сообщений и обновлять текущие сообщения в памяти соответствующим образом. Службы коммуникации Azure поддерживают список событий, на которые можно подписываться.

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

Добавьте этот код вместо комментария <RECEIVE A CHAT MESSAGE FROM A CHAT THREAD> в файл client.js. Обновите вкладку браузера, и в консоли отобразится сообщение Notification chatMessageReceived.

Кроме того, можно получать сообщения чата, выполняя опрос метода listMessages через определенные интервалы.


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

Добавьте этот код вместо комментария <LIST MESSAGES IN A CHAT THREAD> в файл client.js. Обновите вкладку. В консоли вы должны увидеть список сообщений, отправленных в этом потоке чата.

listMessagesвозвращает различные типы сообщений, которые можно определить.chatMessage.type

Дополнительные сведения см. в разделе о типах сообщений.

Добавление пользователя в качестве участника в поток чата

После создания потока чата можно добавлять и удалять пользователей. Добавляя пользователей, вы предоставляете им доступ для отправки сообщений в поток чата, а также добавления или удаления других участников.

Перед вызовом addParticipants метода убедитесь, что вы приобрели новый маркер доступа и удостоверение для этого пользователя. Пользователю потребуется маркер доступа для инициализации своего клиента чата.

addParticipantsRequest описывает объект запроса, а в participants приведены участники, добавляемые в поток чата.

  • id (требуется) — это идентификатор обмена данными, который должен быть добавлен в поток чата.
  • displayName (необязательно) — это отображаемое имя для участника потока.
  • shareHistoryTime (необязательно) — это время, в течение которого участнику предоставляется доступ к журналу чата. Чтобы предоставить общий доступ к журналу с момента запуска потока чата, установите для этого свойства любую дату, равную или меньше времени создания потока. Чтобы в журнале отображались только записи с момента добавления участника, задайте для свойства текущую дату. Чтобы предоставить общий доступ к части журнала, задайте для него дату по своему усмотрению.

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

await chatThreadClient.addParticipants(addParticipantsRequest);

Замените NEW_PARTICIPANT_USER_IDновым идентификатором пользователя и добавьте этот код вместо комментария <ADD NEW PARTICIPANT TO THREAD> в файл client.js.

Вывод списка пользователей в потоке чата

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

Добавьте этот код вместо комментария <LIST PARTICIPANTS IN A THREAD> в файл client.js, обновите вкладку браузера и проверьте консоль. Вы увидите сведения о пользователях чата:

Удаление пользователя из потока чата

Аналогично тому, как выполняется добавление участников, вы можете удалять их из потока чата. Чтобы удалить, необходимо отслеживать идентификаторы добавленных участников.

Используйте метод removeParticipant, где participant — это пользователь, удаляемый из потока.


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

Замените PARTICIPANT_ID идентификатором пользователя, используемым на предыдущем шаге (<NEW_PARTICIPANT_USER_ID>). Добавьте этот код вместо комментария <REMOVE PARTICIPANT FROM THREAD> в файл client.js.

Подписка на состояние подключения уведомлений в режиме реального времени

Подписка на события realTimeNotificationConnected и realTimeNotificationDisconnected позволяет узнать, когда подключение к серверу вызова активно.

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

Пример кода

Итоговый код для этого краткого руководства можно найти на сайте GitHub.

Необходимые компоненты

Перед началом работы нужно сделать следующее:

Установка

Создание приложения Python

Откройте терминал или командное окно, создайте каталог для своего приложения и перейдите к нему.

mkdir chat-quickstart && cd chat-quickstart

Используйте текстовый редактор, чтобы создать файл с именем start-chat.py в корневом каталоге проекта. Создайте структуру программы, включая простую обработку исключений. В следующих разделах показано, как добавить в этот файл весь исходный код для примера из этого краткого руководства.

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)

Установка пакета SDK

Чтобы установить пакет SDK, используйте следующую команду:


pip install azure-communication-chat

Объектная модель

Следующие классы и интерфейсы реализуют некоторые основные функции пакета SDK для чата Служб коммуникации Azure для Python.

Имя Описание
ChatClient Этот класс требуется для реализации возможностей чата. Его можно создать с помощью сведений о подписке и использовать для создания, получения и удаления потоков.
ChatThreadClient Этот класс требуется для реализации возможностей потоков чата. Экземпляр можно получить с помощью ChatClient для отправки, получения, обновления и удаления сообщений. Кроме того, он позволяет добавлять, удалять и получать пользователей и отправлять уведомления о вводе и прочтении.

Создание клиента чата

Чтобы создать клиент чата, используйте конечную точку Служб коммуникации и маркер доступа, который был создан в рамках подготовки.

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

В этом кратком руководстве не описан процесс создания уровня служб, который будет управлять маркерами для приложения чата, но мы рекомендуем это сделать. Дополнительные сведения см. в разделе "Архитектура чатов" в статье Понятия, связанные с чатами.

Запуск потока чата

Для создания потока чата используйте метод create_chat_thread.

  • Для указания темы беседы используйте topic. Тему можно обновить после создания беседы чата с помощью функции update_thread.
  • Используйте thread_participants, чтобы получить список ChatParticipant, добавляемых в беседу чата. Объект ChatParticipant принимает тип CommunicationUserIdentifier как user.

CreateChatThreadResult — это возвращаемый результат создания беседы. Его можно использовать для получения id созданной беседы чата. Затем id можно использовать, чтобы получить объект ChatThreadClient с помощью метода get_chat_thread_client. ChatThreadClient можно использовать для выполнения других операций чата в этой беседе.

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)

Получение клиента потока чата

Метод get_chat_thread_client возвращает клиент потока для имеющегося потока. Его можно использовать для выполнения операций с созданной беседой. Например, можно добавлять участников и отправлять сообщения. thread_id — это уникальный идентификатор существующей беседы чата.

ChatThreadClient можно использовать для выполнения других операций чата в этой беседе.

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

Перечисление всех потоков чата

Метод list_chat_threads возвращает итератор типа ChatThreadItem.

  • Используйте start_time для указания самой ранней точки во времени, до которой будут получены беседы чата.
  • Используйте results_per_page, чтобы указать максимальное число возвращаемых потоков чата для каждой страницы.

Итератор [ChatThreadItem] является ответом, возвращенным из списка бесед.

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)

Отправка сообщения в поток чата

Используйте метод send_message для отправки сообщения в созданную беседу чата, идентифицируемую с помощью thread_id.

  • Используйте content, чтобы указать содержимое сообщения в чате.
  • Используйте chat_message_type, чтобы указать тип содержимого сообщения. Возможные значения: text и html. Если значение не указано, по умолчанию используется text.
  • Используйте sender_display_name, чтобы указать отображаемое имя отправителя.
  • Используйте metadata, если нужно в сообщение нужно добавить дополнительные данные. Это поле позволяет разработчикам расширить функциональные возможности сообщений чата и при необходимости добавить в сообщения дополнительные сведения. Например, при отправке ссылки на файл в сообщении в его метаданных можно указать hasAttachment:true, чтобы приложение получателя учитывало это и показывало сообщение соответствующим образом.

SendChatMessageResult — это ответ, возвращенный в результате отправки сообщения. Он содержит уникальный идентификатор сообщения.

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)

Получение сообщений из потока чата

Кроме того, можно получать сообщения чата, выполняя опрос метода list_messages через определенные интервалы.

  • Используйте results_per_page, чтобы указать максимальное число возвращаемых сообщений для каждой страницы.
  • Используйте start_time для указания самой ранней точки во времени, до которой будут получены сообщения.

Итератор [ChatMessage] является ответом, возвращенным из списка сообщений.

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 возвращает последнюю версию сообщения, включая все изменения или удаления, произошедшие с сообщением, с помощью update_message и delete_message. Для удаленных сообщений ChatMessage.deleted_on возвращает значение datetime, указывающее, когда это сообщение было удалено. Для измененных сообщений ChatMessage.edited_on возвращает значение datetime, указывающее, когда это сообщение было изменено. Доступ к исходному времени создания сообщения можно получить с помощью ChatMessage.created_on, который можно использовать для упорядочения сообщений.

list_messages возвращает различные типы сообщений, которые могут быть идентифицированы с помощью ChatMessage.type.

Дополнительные сведения см. в статье Типы сообщений.

Отправка уведомления о прочтении

Для публикации события уведомления о прочтении в беседе от имени пользователя используйте метод send_read_receipt.

  • Используйте message_id, чтобы указать идентификатор последнего сообщения, прочитанного текущим пользователем.
content='hello world'

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

Добавление пользователя в качестве участника в поток чата

После создания беседы чата можно добавлять и удалять пользователей. Добавляя пользователей, вы предоставляете им возможность отправлять сообщения в беседу чата, а также добавлять или удалять других участников. Перед вызовом метода add_participants убедитесь, что вы получили новый маркер доступа и удостоверение для этого пользователя. Пользователю требуется маркер доступа для инициализации клиента чата.

В беседу чата можно добавить одного или нескольких пользователей с помощью метода add_participants, если для всех пользователей доступен новый маркер доступа и идентификатор.

возвращается list(tuple(ChatParticipant, CommunicationError)); Если участник успешно добавлен, ожидается пустой список. Если при добавлении участника произошла ошибка, список заполняется соответствующими участниками вместе с возникшей ошибкой.

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)

Перечисление участников в беседе в чате

Аналогично тому, как выполняется добавление участников, вы можете перечислить их в потоке.

Используйте list_participants, чтобы получить участников потока. Обе следующие команды являются необязательными.

  • Используйте results_per_page, чтобы указать максимальное число участников, возвращаемых на каждой странице.
  • Используйте skip, чтобы пропустить участников вплоть до указанной позиции в ответе.

Итератор [ChatParticipant] является ответом, возвращаемым из списка участников.

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)

Выполнение кода

Запустите приложение из каталога приложения с помощью команды python.

python start-chat.py

Пример кода

Итоговый код для этого краткого руководства можно найти на сайте GitHub.

Необходимые компоненты

Установка

Создание нового приложения Java

Откройте терминал или командное окно и перейдите в каталог, в котором необходимо создать приложение Java. Выполните приведенную ниже команду, чтобы создать проект Java из шаблона maven-archetype-quickstart.

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

Вы заметите, что цель generate создала каталог с тем же именем, что и у artifactId. В этом каталоге src/main/java directory содержит исходный код проекта, каталог src/test/java содержит источник теста, а файл pom.xml является объектной моделью проекта или POM.

Обновите файл POM приложения, чтобы использовать Java 8 или более поздней версии:

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

Добавление ссылок на пакет для пакета SDK для чата

В файле POM добавьте ссылку на пакет azure-communication-chat с помощью API-интерфейсов для чатов:

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

Для проверки подлинности клиент должен добавить ссылку на пакет azure-communication-common:

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

Объектная модель

Следующие классы и интерфейсы реализуют некоторые основные функции пакета SDK для чата Служб коммуникации Azure для Java.

Имя Описание
ChatClient Этот класс требуется для реализации всех функций чата. Его можно создать с помощью сведений о подписке и использовать для создания, получения и удаления потоков.
ChatAsyncClient Этот класс требуется для реализации всех асинхронных функций чата. Его можно создать с помощью сведений о подписке и использовать для создания, получения и удаления потоков.
ChatThreadClient Этот класс требуется для реализации всех функций потоков чата. Вы получаете экземпляр с помощью ChatClient и используете его для отправки, получения, обновления и удаления сообщений, добавления, удаления и получения пользователей, а также для отправки уведомлений о вводе и уведомления о прочтении.
ChatThreadAsyncClient Этот класс требуется для реализации всех асинхронных функций потоков чата. Вы получаете экземпляр с помощью ChatAsyncClient и используете его для отправки/получения/обновления/удаления сообщений, добавления/удаления/получения пользователей и отправки уведомлений о вводе и уведомления о прочтении.

Создание клиента чата

Чтобы создать клиент чата, вы будете использовать конечную точку Служб коммуникации и маркер доступа, который был создан на шаге предварительных требований. Маркеры доступа пользователей позволяют создавать клиентские приложения, которые напрямую проходят проверку подлинности в Службах коммуникации Azure. После создания этих маркеров на сервере передайте их обратно клиентскому устройству. Для передачи маркера клиенту чата необходимо использовать класс CommunicationTokenCredential из общего пакета SDK.

Дополнительные сведения об архитектуре чатов

При добавлении операторов импорта обязательно добавляйте только импорты из пространств имен com.azure.communication.chat и com.azure.communication.chat.models, а не из com.azure.communication.chat.implementation. В файле App.java, созданном с помощью Maven, можно использовать следующий код:

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

Запуск потока чата

Для создания потока чата используйте метод createChatThread. createChatThreadOptions используется для описания запроса потока.

  • Для указания раздела в этом чате используйте параметр topic конструктора. Раздел можно обновить после создания потока чата с помощью функции UpdateThread.
  • Используйте participants, чтобы получить список участников потока, добавляемых в поток. ChatParticipant принимает пользователя, которого вы создали при изучении краткого руководства о маркере доступа пользователя.

CreateChatThreadResult — это ответ, возвращаемый при создании потока чата. Он содержит getChatThread() метод, который возвращает ChatThread объект, который можно использовать для получения клиента потока, из которого можно получить ChatThreadClient выполнение операций в созданном потоке: добавление участников, отправка сообщения и т. д. Объект ChatThread также содержит getId() метод, который получает уникальный идентификатор потока.

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

Перечисление потоков чата

Для получения списка существующих потоков чата используйте метод listChatThreads.

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

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

Получение клиента потока чата

Метод getChatThreadClient возвращает клиент потока для имеющегося потока. Его можно использовать для выполнения операций в созданном потоке: добавления участников, отправки сообщения и т. д. chatThreadId — это уникальный идентификатор существующего потока чата.

ChatThreadClient chatThreadClient = chatClient.getChatThreadClient(chatThreadId);

Отправка сообщения в поток чата

sendMessage Используйте метод для отправки сообщения в созданный поток, идентифицируемый chatThreadId. sendChatMessageOptions используется для описания запроса сообщения чата.

  • Используйте content, чтобы указать содержимое сообщения в чате.
  • Используйте type для указания типа содержимого сообщения в чате, текста или HTML.
  • Используйте senderDisplayName, чтобы указать отображаемое имя отправителя.
  • Используйте metadata, если нужно в сообщение нужно добавить дополнительные данные. Это поле позволяет разработчикам расширить функциональные возможности сообщений чата и при необходимости добавить в сообщения дополнительные сведения. Например, при совместном использовании ссылки на файл в сообщении может потребоваться добавить hasAttachment:true в метаданные, чтобы приложение получателя могло проанализировать их и отобразить соответствующим образом.

sendChatMessageResult ответа содержит id, который является уникальным идентификатором сообщения.

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

Получение сообщений из потока чата

Вы можете получать сообщения чата, выполняя опрос метода listMessages на клиенте потока чата через определенные интервалы.

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

listMessages возвращает последнюю версию сообщения, включая все изменения или удаления, произошедшие с сообщением, с помощью .editMessage() и .deleteMessage(). Для удаленных сообщений chatMessage.getDeletedOn() возвращает значение даты и времени, указывающее, когда это сообщение было удалено. Для измененных сообщений chatMessage.getEditedOn() возвращает значение даты и времени, указывающее, когда это сообщение было изменено. Доступ к исходному времени создания сообщения можно получить с помощью chatMessage.getCreatedOn(), который также можно использовать для упорядочения сообщений.

Дополнительные сведения о типах сообщений см. в разделе Типы сообщений.

Отправка уведомления о прочтении

Для публикации события уведомления о прочтении в потоке от имени пользователя используйте метод sendReadReceipt. chatMessageId — это уникальный идентификатор считанного сообщения в чате.

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

Перечисление участников чата

Для получения страничной коллекции, содержащей участников потока чата, идентифицируемого значением chatThreadId, используйте listParticipants.

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

Добавление пользователя в качестве участника в поток чата

После создания потока чата можно добавлять и удалять пользователей. Добавляя пользователей, вы предоставляете им доступ для отправки сообщений в поток чата, а также добавления или удаления других участников. Необходимо начать с получения нового маркера доступа и удостоверения для этого пользователя. Перед вызовом метода addParticipants убедитесь, что вы приобрели новый маркер доступа и удостоверение для этого пользователя. Пользователю потребуется маркер доступа для инициализации своего клиента чата.

Для добавления участников в поток используйте метод addParticipants.

  • communicationIdentifier (обязательно) — это идентификатор CommunicationIdentifier, созданный вами с помощью CommunicationIdentityClient при изучении краткого руководства по работе с пользовательским маркером доступа.
  • displayName (необязательно) — это отображаемое имя для участника потока.
  • shareHistoryTime (необязательно) — это время, в течение которого участнику предоставляется доступ к журналу чата. Чтобы предоставить общий доступ к журналу с момента запуска потока чата, установите для этого свойства любую дату, равную или меньше времени создания потока. Чтобы в журнале отображались только записи с момента добавления участника, задайте для свойства текущую дату. Чтобы предоставить общий доступ к части журнала, задайте для него требуемую дату.
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);

Выполнение кода

Перейдите в каталог, содержащий файл pom.xml, и скомпилируйте проект с помощью следующей команды mvn.

mvn compile

Затем выполните сборку пакета.

mvn package

Выполните следующую команду mvn для запуска приложения.

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

Пример кода

Итоговый код для этого краткого руководства можно найти на сайте GitHub.

Необходимые компоненты

Перед началом работы нужно сделать следующее:

  • Создайте учетную запись Azure с активной подпиской. Дополнительные сведения см. на странице Создайте бесплатную учетную запись Azure уже сегодня.

  • Установите Android Studio. В этом кратком руководстве эта среда будет использоваться для создания приложения Android для установки зависимостей.

  • Создание ресурса Служб коммуникации Azure. Дополнительные сведения см. в кратком руководстве по созданию ресурсов Служб коммуникации и управлению ими. Для этого краткого руководства необходимо записать конечную точку ресурса и строка подключения.

  • Создайте двух пользователей служб коммуникации и оставьте их маркером доступа пользователей. Не забудьте задать область чата и запишите строку токена и строку user_id. При работе с этим кратким руководством мы создадим поток с первым участником, а затем добавим в поток второго участника. Вы также можете использовать Azure CLI и выполнить приведенную ниже команду с помощью строка подключения для создания пользователя и маркера доступа.

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

    Дополнительные сведения см. в статье "Создание маркеров доступа и управление ими" с помощью Azure CLI.

Установка

Создание приложения Android

  1. Запустите Android Studio и выберите Create a new project.
  2. В следующем окне выберите шаблон проекта Empty Activity.
  3. При выборе параметров введите имя проекта ChatQuickstart.
  4. Нажмите кнопку Next (Далее) и выберите каталог, в котором нужно создать проект.

Установка библиотек

Мы будем использовать Gradle для установки необходимых зависимостей Служб коммуникации. В командной строке перейдите в корневой каталог проекта ChatQuickstart. Откройте файл build.gradle приложения и добавьте в целевой объект ChatQuickstart следующие зависимости:

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

Номера последних версий библиотек можно узнать по адресам https://search.maven.org/artifact/com.azure.android/azure-communication-common и https://search.maven.org/artifact/com.azure.android/azure-communication-chat.

Исключение файлов метаданных в параметрах упаковки в файле 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")
    }
}

(Альтернативный вариант) Установка библиотек с помощью Maven

Чтобы импортировать библиотеку в проект с помощью системы сборки Maven, добавьте ее в раздел dependencies файла приложения pom.xml, указав идентификатор артефакта и версию, которая будет использоваться.

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

Настройка функции Azure

Дополнительные сведения проверка интеграции функций Azure. Настоятельно рекомендуется интегрировать с функцией Azure, чтобы избежать параметров приложения жесткого программирования.

Настройте константы приложения:

Создайте класс ApplicationConstants , в котором хранятся все константы приложения:

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

Настройка заполнителей

Откройте файл MainActivity.java и измените его. В этом кратком руководстве мы добавим код MainActivityв консоль и просмотрите выходные данные в консоли. В этом кратком руководстве не рассматривается создание пользовательского интерфейса. В верхней части файла импортируйте Azure Communication CommonAzure Communication Chatи другие системные библиотеки:

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;

Скопируйте приведенный ниже код и вставьте его в класс MainActivity в файле 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());
        }
    }

Инициализация параметров приложения

Примечание.

Инициализация ApplicationConstants должна быть добавлена, MainActivity.java если выполняется ЛИБО из следующих условий: 1. Функция push-уведомлений не включена. 2. Версия библиотеки чата коммуникации Azure для Android — < 2.0.0. В противном случае обратитесь к шагу 11 в push-уведомлениях Android. Ознакомьтесь с примером ПРИЛОЖЕНИЯ версии пакета SDK, которую вы используете для получения справки.

ACS_ENDPOINTи FIRST_USER_IDFIRST_USER_ACCESS_TOKEN возвращаются из вызова функции Azure. Дополнительные сведения проверка интеграции функций Azure. Мы используем ответ вызова функции Azure для инициализации списка параметров:

  • ACS_ENDPOINT: конечная точка ресурса Служб коммуникации.
  • FIRST_USER_ID и SECOND_USER_ID: допустимые идентификаторы пользователей служб коммуникации, созданные ресурсом Служб коммуникации.
  • FIRST_USER_ACCESS_TOKEN: маркер доступа служб коммуникации для <FIRST_USER_ID>.

Блок кода для инициализации параметров приложения путем вызова функции Azure:

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

Создание клиента чата

Замените комментарий <CREATE A CHAT CLIENT> следующим кодом (вставьте операторы import в начало файла):

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

Объектная модель

Следующие классы и интерфейсы реализуют некоторые основные функции пакета SDK для чата Служб коммуникации для JavaScript.

Имя Описание
ChatClient/ChatAsyncClient Этот класс требуется для реализации всех функций чата. Его экземпляр можно создать с помощью сведений о подписке и использовать для создания, получения и удаления потоков, а также для подписки на события чата.
ChatThreadClient/ChatThreadAsyncClient Этот класс требуется для реализации всех функций потоков чата. Вы получаете экземпляр с помощью ChatClient и используете его для отправки, получения, обновления и удаления сообщений, добавления, удаления и получения пользователей, а также для отправки уведомлений о вводе и уведомления о прочтении.

Запуск потока чата

Мы воспользуемся ChatAsyncClient, чтобы создать поток с первым пользователем.

Замените комментарий <CREATE A CHAT THREAD> следующим фрагментом кода:

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

Получение клиента потока чата

Теперь, когда создан поток чата, получим ChatThreadAsyncClient для выполнения операций в потоке. Замените комментарий <CREATE A CHAT THREAD CLIENT> следующим фрагментом кода:

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

Отправка сообщения в поток чата

Теперь отправим сообщение в этот поток.

Замените комментарий <SEND A MESSAGE> следующим фрагментом кода:

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

Получение сообщений из потока чата

Уведомления в реальном времени

С помощью оповещений в реальном времени можно подписываться на новые входящие сообщения и обновлять текущие сообщения в памяти соответствующим образом. Службы коммуникации Azure поддерживают список событий, на которые можно подписываться.

Замените комментарий <RECEIVE CHAT MESSAGES> следующим кодом (вставьте операторы import в начало файла):


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

Важно!

Известная проблема: при использовании в Android пакетов SDK для вызовов и чатов вместе в одном приложении функция уведомлений в режиме реального времени пакета SDK для чатов не работает. Может возникнуть проблема с разрешением зависимостей. Пока мы работаем над решением, функцию уведомлений в режиме реального времени можно отключить, добавив следующие сведения о зависимостях в файл приложения build.gradle, и вместо этого опрашивать API-интерфейс GetMessages, чтобы отображать входящие сообщения для пользователей.

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'

Обратите внимание, что если после внесения описанного выше изменения приложение попытается коснуться любого API-интерфейса уведомлений, например, chatAsyncClient.startRealtimeNotifications() или chatAsyncClient.addEventHandler(), то возникнет ошибка среды выполнения.

Push-уведомления

Для получения дополнительных сведений проверка push-уведомлений Android.

Добавление пользователя в качестве участника в поток чата

Замените комментарий <ADD A USER> следующим фрагментом кода:

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

Вывод списка пользователей в потоке

Замените комментарий <LIST USERS> следующим кодом (вставьте операторы импорта в начало файла):

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

Удаление пользователя из потока чата

Теперь удалим второго пользователя из потока.

Замените комментарий <REMOVE A USER> следующим фрагментом кода:

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

Отправка уведомления о вводе

Замените комментарий <SEND A TYPING NOTIFICATION> следующим фрагментом кода:

chatThreadAsyncClient.sendTypingNotification().get();

Отправка уведомления о прочтении

Отправим уведомление о прочтении сообщения, отправленного выше.

Замените комментарий <SEND A READ RECEIPT> следующим фрагментом кода:

chatThreadAsyncClient.sendReadReceipt(chatMessageId).get();

Получение списка уведомлений о прочтении

Замените комментарий <READ RECEIPTS> следующим фрагментом кода:

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

Выполнение кода

В Android Studio нажмите кнопку "Run" (Выполнить), чтобы выполнить сборку и запуск проекта. В консоли можно просмотреть выходные данные кода и средства ведения журнала из ChatClient.

Пример кода

Итоговый код для этого краткого руководства можно найти на сайте GitHub.

Необходимые компоненты

Перед началом работы нужно сделать следующее:

Установка

Создание нового приложения C#

В окне консоли (cmd, PowerShell или Bash) выполните команду dotnet new, чтобы создать консольное приложение с именем ChatQuickstart. Эта команда создает простой проект "Hello World" на языке C# с одним файлом исходного кода Program.cs.

dotnet new console -o ChatQuickstart

Измените каталог на только что созданную папку приложения и выполните команду dotnet build, чтобы скомпилировать приложение.

cd ChatQuickstart
dotnet build

Установка пакета

Установка пакета SDK для чата Служб коммуникации Azure для .NET

dotnet add package Azure.Communication.Chat

Объектная модель

Указанные ниже классы реализуют некоторые основные функции пакета SDK для чата Служб коммуникации Azure для C#.

Имя Описание
ChatClient Этот класс требуется для реализации всех функций чата. Его можно создать с помощью сведений о подписке и использовать для создания, получения и удаления потоков.
ChatThreadClient Этот класс требуется для реализации всех функций потоков чата. Вы получаете экземпляр с помощью ChatClient и используете его для отправки, получения, обновления и удаления сообщений, добавления, удаления и получения участников, а также для отправки уведомлений о вводе и уведомления о прочтении.

Создание клиента чата

Чтобы создать клиент чата, вы будете использовать конечную точку Службы коммуникации и маркер доступа, который был создан в рамках предварительных требований. Чтобы создать пользователя и выдать маркер для передачи клиенту чата, необходимо использовать класс CommunicationIdentityClient из пакета SDK для удостоверений.

Дополнительные сведения о маркерах доступа пользователей см. здесь.

В этом кратком руководстве не рассматривается создание уровня служб для управления маркерами для приложения чата, хотя рекомендуется. Дополнительные сведения об архитектуре чатов

Скопируйте приведенные ниже фрагменты кода и вставьте их в исходный файл 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);
        }
    }
}

Запуск потока чата

Для создания потока чата используйте метод createChatThread в ChatClient

  • Для указания раздела в этом чате используйте topic. Раздел можно обновить после создания потока чата с помощью функции UpdateTopic.
  • Используйте свойство participants для передачи списка объектов ChatParticipant, добавляемых в поток чата. Объект ChatParticipant инициализирован с помощью объекта CommunicationIdentifier. CommunicationIdentifier должен иметь тип CommunicationUserIdentifier, MicrosoftTeamsUserIdentifier или PhoneNumberIdentifier. Например, чтобы получить CommunicationIdentifier объект, необходимо передать идентификатор доступа, созданный с помощью инструкции для создания пользователя.

Объект ответа из метода createChatThread содержит подробные сведения о chatThread. Для взаимодействия с операциями потока чата, такими как добавление участников, отправка сообщения, удаление сообщения и т. д., необходимо создать экземпляр клиента chatThreadClient с помощью метода GetChatThreadClient в клиенте 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;

Получение клиента потока чата

Метод GetChatThreadClient возвращает клиент потока для имеющегося потока. Его можно использовать для выполнения операций в созданном потоке: добавления участников, отправки сообщения и т. д. thread_id — уникальный идентификатор имеющегося потока чата.

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

Перечисление всех потоков чата

Чтобы получить все потоки чата, в которых участвует пользователь, используйте GetChatThreads.

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

Отправка сообщения в поток чата

Для отправки сообщения в поток используйте SendMessage.

  • Используется content для предоставления содержимого сообщения.
  • Используйте type, чтобы указать тип содержимого сообщения, например "Text" или "HTML". Если этот параметр не задан, используется тип "Text".
  • Используйте senderDisplayName, чтобы указать отображаемое имя отправителя. Если этот параметр не задан, используется пустая строка.
  • Используйте metadata, если нужно в сообщение нужно добавить дополнительные данные. Это поле позволяет разработчикам расширить функциональные возможности сообщений чата и при необходимости добавить в сообщения дополнительные сведения. Например, при отправке ссылки на файл в сообщении в его метаданных можно указать hasAttachment:true, чтобы приложение получателя учитывало это и показывало сообщение соответствующим образом.
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;

Получение сообщений из потока чата

Вы можете получать сообщения чата, выполняя опрос метода GetMessages на клиенте потока чата через определенные интервалы.

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

GetMessages принимает необязательный параметр DateTimeOffset. Если это смещение указано, вы получите сообщения, которые были получены, обновлены или удалены после него. Обратите внимание, что сообщения, полученные до смещения времени, но исправлены или удалены после него, также будут возвращены.

GetMessages возвращает последнюю версию сообщения, включая все изменения или удаления, произошедшие с сообщением, с помощью UpdateMessage и DeleteMessage. Для удаленных сообщений chatMessage.DeletedOn возвращает значение даты и времени, указывающее, когда это сообщение было удалено. Для измененных сообщений chatMessage.EditedOn возвращает значение даты и времени, указывающее, когда это сообщение было изменено. Доступ к исходному времени создания сообщения можно получить с помощью chatMessage.CreatedOn, который также можно использовать для упорядочения сообщений.

GetMessages возвращает различные типы сообщений, которые могут быть идентифицированы с помощью chatMessage.Type. Это следующие типы:

  • Text: регулярное сообщение чата, отправленное членом потока.

  • Html: форматированное текстовое сообщение. Обратите внимание, что сейчас пользователи Служб коммуникации не могут отправить сообщения с форматированным текстом. Этот тип сообщений поддерживается в сообщениях, отправленных от пользователей Teams пользователям Служб коммуникации в сценариях взаимодействия с Teams.

  • TopicUpdated: системное сообщение, указывающее, что раздел обновлен. (только чтение)

  • ParticipantAdded: системное сообщение о том, что один или несколько участников были добавлены в поток чата. (только чтение)

  • ParticipantRemoved: системное сообщение, указывающее, что участник был удален из потока чата.

Дополнительные сведения см. в разделе о типах сообщений.

Добавление пользователя в качестве участника в поток чата

После создания потока можно добавлять и удалять пользователей. Добавляя пользователей, вы предоставляете им возможность отправлять сообщения в поток, а также добавлять или удалять других участников. Перед вызовом AddParticipants убедитесь, что вы получили новый маркер доступа и удостоверение для этого пользователя. Пользователю потребуется маркер доступа для инициализации своего клиента чата.

Используйте AddParticipants для добавления одного или нескольких участников в поток чата. Ниже приведены поддерживаемые атрибуты для каждого участника потока:

  • communicationUser (обязательно) — это идентификатор участника потока.
  • displayName (необязательно) — это отображаемое имя для участника потока.
  • shareHistoryTime (необязательно) — это время, начиная с которого участнику предоставляется доступ к журналу чата.
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);

Получение участников потока

Используйте GetParticipants для получения участников потока чата.

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

Отправка уведомления о прочтении

Используйте SendReadReceipt, чтобы уведомить других участников о том, что пользователь прочитал сообщение.

await chatThreadClient.SendReadReceiptAsync(messageId: messageId);

Выполнение кода

Запустите приложение из каталога приложения с помощью команды dotnet run.

dotnet run

Пример кода

Итоговый код для этого краткого руководства можно найти на сайте GitHub.

Необходимые компоненты

Перед началом работы нужно сделать следующее:

  • Создайте учетную запись Azure с активной подпиской. Дополнительные сведения см. на странице Создайте бесплатную учетную запись Azure уже сегодня.

  • Установите Xcode и CocoaPods. Xcode вам потребуется для создания приложения iOS для этого краткого руководства, а CocoaPods — для установки зависимостей.

  • Создание ресурса Служб коммуникации Azure. Дополнительные сведения см. в статье Краткое руководство. Создание ресурсов Служб коммуникации Azure и управление ими. Для этого краткого руководства необходимо записать конечную точку ресурса и строка подключения.

  • Создайте двух пользователей в Службы коммуникации Azure и оставьте их маркером доступа пользователей. Не забудьте задать область чата и запишите строку токена, а также строку user_id. В этом кратком руководстве показано, как создать поток с первым участником, а затем добавить в этот поток второго участника. Вы также можете использовать Azure CLI и выполнить приведенную ниже команду с помощью строка подключения для создания пользователя и маркера доступа.

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

    Дополнительные сведения см. в статье "Создание маркеров доступа и управление ими" с помощью Azure CLI.

Установка

Создание нового приложения iOS

Запустите Xcode и щелкните Create a new Xcode project (Создать новый проект Xcode). Теперь выберите платформу iOS и шаблон App (Приложение).

Введите имя проекта ChatQuickstart. Затем выберите Storyboard (Раскадровка) в качестве интерфейса, UIKit App Delegate (Делегат приложения UIKit) в качестве жизненного цикла и Swift в качестве языка.

Щелкните Next (Далее) и выберите каталог, в котором нужно создать проект.

Установка библиотек

Установите необходимые зависимости Служб коммуникации с помощью CocoaPods.

В командной строке перейдите в корневой каталог проекта iOS ChatQuickstart. Создайте Podfile с помощью следующей команды: pod init.

Откройте Podfile и добавьте следующие зависимости в целевой объект ChatQuickstart:

pod 'AzureCommunicationChat', '~> 1.3.4'

Установите зависимости с помощью следующей команды: pod install. Обратите внимание, что при этом также создается рабочая область Xcode.

После выполнения pod install повторно откройте проект в Xcode, выбрав только что созданный экземпляр .xcworkspace.

Настройка заполнителей

Откройте в Xcode файл рабочей области ChatQuickstart.xcworkspace, а затем откройте ViewController.swift.

В этом кратком руководстве показано, как добавить код в класс viewController и просмотреть выходные данные в консоли Xcode. В этом кратком руководстве не описан процесс создания пользовательского интерфейса в iOS.

В начале файла viewController.swift импортируйте библиотеки AzureCommunication и AzureCommunicatonChat:

import AzureCommunicationCommon
import AzureCommunicationChat

Скопируйте следующий код в метод viewDidLoad() класса 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)")
            }
        }
    }

В демонстрационных целях для синхронизации кода используется семафор. В следующих шагах мы заменим заполнители примерами кода, используя библиотеки чата Служб коммуникации Azure.

Создание клиента чата

Чтобы создать клиент чата, вы будете использовать конечную точку Службы коммуникации и маркер доступа, который был создан в рамках предварительных требований.

Дополнительные сведения о маркерах доступа пользователей см. здесь.

В этом кратком руководстве не рассматривается создание уровня служб для управления маркерами для приложения чата, хотя рекомендуется. Дополнительные сведения об архитектуре чатов

Замените комментарий <CREATE A CHAT CLIENT> на следующий фрагмент кода.

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
)

Замените <ACS_RESOURCE_ENDPOINT> значением конечной точки для ресурса Служб коммуникации Azure. Замените <ACCESS_TOKEN> допустимым маркером доступа Служб коммуникации.

Объектная модель

Следующие классы и интерфейсы реализуют некоторые основные функции пакета SDK для чата Служб коммуникации Azure для iOS.

Имя Описание
ChatClient Этот класс требуется для реализации возможностей чата. Его экземпляр можно создать с помощью сведений о подписке и использовать для создания, получения и удаления потоков, а также для подписки на события чата.
ChatThreadClient Этот класс требуется для реализации возможностей потоков чата. Экземпляр можно получить с помощью ChatClient для отправки, получения, обновления и удаления сообщений. Кроме того, он позволяет добавлять, удалять и получать пользователей и отправлять уведомления о вводе и прочтении.

Запуск потока чата

CreateChatThreadResult — это ответ, возвращаемый при создании потока чата. Он содержит свойство chatThread, которое является объектом ChatThreadProperties. Этот объект содержит threadId, который можно использовать для получения ChatThreadClient для выполнения операций в созданном потоке: добавление участников, отправка сообщения и т. д.

Замените комментарий <CREATE A CHAT THREAD> на следующий фрагмент кода.

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

Замените <USER_ID> допустимым идентификатором пользователя Служб коммуникации.

Здесь нужно настроить семафор, чтобы продолжать работу только после сигнала завершающего обработчика. На следующих шагах вы примените threadId из ответа завершающего обработчика.

Перечисление всех потоков чата

После создания потока чата можно получить список всех потоков в этом чате, вызвав метод listChatThreads из ChatClient. Замените комментарий <LIST ALL CHAT THREADS> следующим фрагментом кода:

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

Получение клиента потока чата

Метод createClient возвращает ChatThreadClient для потока, который уже существует. Его можно использовать для выполнения операций в созданном потоке: добавления участников, отправки сообщения и т. д. Идентификатор thread_id — это уникальный идентификатор имеющегося потока чата.

Замените комментарий <GET A CHAT THREAD CLIENT> следующим фрагментом кода:

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

Отправка сообщения в поток чата

Используйте метод send для отправки сообщения в поток, идентифицируемый с помощью threadId.

SendChatMessageRequest используется для описания запроса сообщения:

  • Используйте content, чтобы указать содержимое сообщения в чате.
  • Используйте senderDisplayName, чтобы указать отображаемое имя отправителя.
  • Используйте type для определения типа сообщения, например text или html.
  • Используйте metadata, если нужно в сообщение нужно добавить дополнительные данные. Это поле позволяет разработчикам расширить функциональные возможности сообщений чата и при необходимости добавить в сообщения дополнительные сведения. Например, при отправке ссылки на файл в сообщении в его метаданных можно указать hasAttachment:true, чтобы приложение получателя учитывало это и показывало сообщение соответствующим образом.

SendChatMessageResult — ответ, возвращаемый при отправке сообщения. Содержит идентификатор, который является уникальным идентификатором сообщения.

Замените комментарий <SEND A MESSAGE> на следующий фрагмент кода.

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

Отправка уведомления о прочтении

Для публикации события уведомления о прочтении в потоке от имени пользователя используйте метод sendReadReceipt. messageId — это уникальный идентификатор считанного сообщения в чате.

Замените комментарий <SEND A READ RECEIPT> на следующий код.

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

Получение сообщений из потока чата

С помощью оповещений в реальном времени можно подписываться на прослушивание новых входящих сообщений и обновлять текущие сообщения в памяти соответствующим образом. Службы коммуникации Azure поддерживают список событий, на которые можно подписываться.

Замените комментарий <RECEIVE MESSAGES> на следующий код. После включения уведомлений попытайтесь отправить новые сообщения, чтобы увидеть 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
    }
})

Кроме того, можно получать сообщения чата, выполняя опрос метода listMessages через определенные интервалы. См. следующий фрагмент кода для 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()

Добавление пользователя в качестве участника в поток чата

После создания потока можно добавлять и удалять пользователей. Добавляя пользователей, вы предоставляете им возможность отправлять сообщения в поток, а также добавлять или удалять других участников. Перед вызовом add убедитесь, что вы получили новый маркер доступа и удостоверение для этого пользователя. Пользователю потребуется маркер доступа для инициализации своего клиента чата.

Используйте метод addChatThreadClient для добавления одного участника или нескольких в чат. Ниже приведены поддерживаемые атрибуты для каждого участника потока:

  • id (обязательно) — это идентификатор участника потока.
  • displayName (необязательно) — это отображаемое имя для участника потока.
  • shareHistoryTime (необязательно) — это время, начиная с которого участнику предоставляется доступ к журналу чата.

Замените комментарий <ADD A USER> следующим фрагментом кода:

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

Замените <USER_ID> значением идентификатора пользователя Служб коммуникации, которого вы хотите добавить.

Вывод списка пользователей в потоке

Используйте метод listParticipants, чтобы получить всех участников для конкретного чата.

Замените комментарий <LIST USERS> следующим фрагментом кода:

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

Push-уведомления

Push-уведомления уведомляют клиентов о входящих сообщениях в потоке чата в ситуациях, когда мобильное приложение не работает на переднем плане. В настоящее время отправка push-уведомлений чата с помощью Центра уведомлений поддерживается для пакета SDK IOS версии 1.3.0. Дополнительные сведения см. в статье "Включить push-уведомление" в приложении чата.

Выполнение кода

В Xcode нажмите кнопку Run (Выполнить), чтобы выполнить сборку и запуск проекта. В консоли можно просмотреть выходные данные кода и средства ведения журнала из ChatClient.

Примечание. Задайте для Build Settings > Build Options > Enable Bitcode значение No. В настоящее время пакет SDK AzureCommunicationChat для iOS не поддерживает включение bitcode, поэтому существует следующая проблема GitHub.

Пример кода

Итоговый код для этого краткого руководства можно найти на сайте GitHub.

Необходимые компоненты

Создать пользователя

Выполните следующие действия в Power Automate с открытым потоком Power Automate в режиме редактирования.

Чтобы добавить новый шаг в рабочий процесс с помощью соединителя удостоверений служб коммуникации:

  1. В конструкторе на шаге, в котором нужно добавить новое действие, выберите новый шаг. Кроме того, чтобы добавить новое действие между шагами, переместите указатель на стрелку между этими шагами, выберите знак плюса (+), а затем нажмите кнопку "Добавить действие".

  2. В поле поиска по операции введите удостоверение служб коммуникации. В списке действий выберите "Создать пользователя".

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

  3. Введите строка подключения. Чтобы получить URL-адрес строка подключения в портал Azure, перейдите к ресурсу Службы коммуникации Azure. В меню ресурсов выберите "Ключи", а затем выберите строку Подключение ion. Щелкните значок копирования, чтобы скопировать строка подключения.

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

  4. Введите имя для подключения.

  5. Выберите "Показать дополнительные параметры" и выберите маркер область. Действие создает маркер доступа и его срок действия с указанным область. Это действие также создает идентификатор пользователя, который является удостоверением пользователя Служб коммуникации.

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

  6. В элементе области маркеров выберите чат.

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

  7. Выберите Создать. Отображается идентификатор пользователя и маркер доступа.

Создание потока чата

  1. Добавьте новое действие.

  2. В поле поиска " Выбор операции " введите чат служб коммуникации. В списке действий выберите "Создать поток чата".

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

  3. Введите URL-адрес конечной точки служб коммуникации. Чтобы получить URL-адрес конечной точки в портал Azure, перейдите к ресурсу Службы коммуникации Azure. В меню ресурсов выберите "Ключи" и выберите "Конечная точка".

  4. Введите имя для подключения.

  5. Выберите маркер доступа, созданный в предыдущем разделе, и добавьте описание раздела потока чата. Добавьте созданного пользователя и введите имя участника.

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

Отправка сообщений

  1. Добавьте новое действие.

  2. В поле поиска " Выбор операции " введите чат служб коммуникации. В списке действий выберите "Отправить сообщение в поток чата".

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

  3. Введите маркер доступа, идентификатор потока, содержимое и имя.

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

Вывод списка сообщений в потоке чата

Чтобы проверить правильность отправки сообщения, выполните следующие действия.

  1. Добавьте новое действие.

  2. В поле поиска " Выбор операции " введите чат служб коммуникации. В списке действий выберите "Список сообщений чата".

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

  3. Введите маркер доступа и идентификатор потока.

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

Тестирование приложения логики

Чтобы вручную запустить рабочий процесс, на панели инструментов конструктора щелкните Запустить. Рабочий процесс создает пользователя, выдает маркер доступа для этого пользователя, а затем удаляет маркер и удаляет пользователя. Дополнительные сведения см. в статье о запуске рабочего процесса.

Теперь выберите "Список сообщений чата". В выходных данных действия проверка для отправленного сообщения.

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

Очистка ресурсов рабочего процесса

Сведения о том, как удалить рабочий процесс приложения логики и связанные с ним ресурсы, см в статье об очистке Logic Apps от ресурсов.

Очистка ресурсов

Если вы хотите отменить и удалить подписку на Службы коммуникации, можно удалить ресурс или группу ресурсов. При удалении группы ресурсов также удаляются все связанные с ней ресурсы. См. сведения об очистке ресурсов.

Следующие шаги

Из этого руководства вы узнали, как выполнить следующие действия:

  • Создание клиента чата
  • создать цепочку с двумя пользователями;
  • отправить сообщение в цепочку;
  • получить сообщения из цепочки;
  • исключить пользователей из цепочки.

Ознакомьтесь с главным имиджевым приложением чата

Полезные ссылки