Добавление чата в приложение

Предварительные условия

• Учетная запись 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>"

export AZURE_COMMUNICATION_ENDPOINT="<yourEndpoint>"

export AZURE_COMMUNICATION_ENDPOINT="<yourEndpoint>"

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

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

setx AZURE_COMMUNICATION_ACCESS_TOKEN "<yourAccessToken>"

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

export AZURE_COMMUNICATION_ACCESS_TOKEN="<yourAccessToken>"

Операции

Начать ветку чата

Используйте команду 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 Communication Services.
• Замените <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.

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

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

• Замените endpointUrl ресурсной конечной точкой Служб коммуникации. Для получения дополнительной информации см. Создание ресурса Azure Communication Services.
• Замените userAccessToken на выданный вами токен.

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

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

npx parcel index.html

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

Azure Communication Chat client created!

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

Следующие классы и интерфейсы обрабатывают некоторые из основных функций SDK чата Azure Communication Services для JavaScript.

Начать чат

Для создания потока чата используйте метод 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.

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

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

• Установите Python 3.7+.

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

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

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

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

Установка

Создание приложения 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.

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

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

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.

Предварительные требования

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

• Среда разработки Java (JDK) версии 8 или более поздней.

• Apache Maven.

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

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

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

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

Настройка

Создание нового приложения 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.

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

Чтобы создать клиент чата, используйте конечную точку службы коммуникации и маркер доступа, созданный в рамках необходимых действий. Маркеры доступа пользователей позволяют создавать клиентские приложения, которые напрямую проходят проверку подлинности в Службах коммуникации 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 для указания типа содержимого сообщения чата: TEXT или 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 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 Function, чтобы избежать жесткого кодирования параметров приложения.

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

Создайте класс 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());
        }
    }

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

ACS_ENDPOINT, FIRST_USER_IDи FIRST_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.

Начать разговор в чате

Используйте нашу 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
    
});

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'

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

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

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

Замените комментарий <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.

Предварительные условия

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

• Установите Visual Studio.

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

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

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

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

Настройка

Создание нового приложения 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#.

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

Чтобы создать клиент чата, используйте конечную точку служб коммуникации и маркер доступа, созданный в рамках необходимых действий. Необходимо использовать класс 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 возвращает клиент потока для имеющегося потока. Его можно использовать для выполнения операций с созданным потоком: добавление участников, отправка сообщения и т. д. threadId — это уникальный идентификатор существующего чата.

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: форматированное текстовое сообщение. Пользователи служб коммуникации в настоящее время не могут отправлять сообщения RichText. Этот тип сообщения поддерживается для сообщений, отправляемых пользователями Teams пользователями служб коммуникации в сценариях взаимодействия Teams.

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

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

• 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 как жизненный цикл и Swift как язык.

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

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

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

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

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

pod 'AzureCommunicationChat', '~> 1.3.6'

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

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

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

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

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

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

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 Communication Services.

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

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

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

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

Замените комментарий <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.

Начать тему чата

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-уведомлений чата с помощью Notification Hub поддерживается для IOS SDK версии 1.3.0.

Дополнительные сведения см. в разделе "Включить push-уведомление" в приложении чата.

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

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

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

Пример кода

Найдите завершенный код для этой статьи в примере добавления чата в приложение GitHub.

Предварительные условия

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

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

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

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

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

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

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

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

   

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

   

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

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

   

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

   

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

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

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

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

   

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

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

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

   

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

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

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

   

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

   

Список сообщений в потоке чата

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

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

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

   

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

   

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

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

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

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

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