Поиск данных через REST API

Статья создана

Yandex Cloud

Обновлена 17 октября 2024 г.

Перед началом работы
Полнотекстовый поиск
- Пример тела запроса для полнотекстового поиска
- Пример тела запроса для полнотекстового поиска с фильтрацией по параметрам
Фильтрация по параметрам
- Пример тела запроса для фильтрации по отдельным параметрам
Получить информацию о диалоге
- Пример тела запроса на получение информации о диалоге
Параметры запросов
- Search-запрос
- Get-запрос

Для поиска данных через REST API вы можете использовать:

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

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

Перед началом работы

Чтобы искать данные через REST API Yandex Cloud:

В консоли управления создайте сервисный аккаунт.
Добавьте сервисный аккаунт в пространство с ролью Data viewer. Это позволит сервисному аккаунту работать с данными в SpeechSense.
Чтобы аутентифицироваться в API Yandex Cloud, создайте API-ключ или IAM-токен для сервисного аккаунта.
Загрузите аудиозаписи или чаты в SpeechSense.

Полнотекстовый поиск

Создайте файл search.json, укажите в нем нужные идентификаторы и параметры для полнотекстового поиска:
```
{
  "organizationId": "<идентификатор_организации>",
  "spaceId": "<идентификатор_пространства>",
  "connectionId": "<идентификатор_подключения>",
  "projectId": "<идентификатор_проекта>",
  "query": {
    "text": "<поисковый_запрос>",
    "channel_number": "<номер_канала>"
  }
}
```
Где:
- organizationId — идентификатор организации, в которой выполняется запрос. Чтобы получить идентификатор, перейдите в сервис Cloud Center и нажмите кнопку под названием организации, в разделе .
- spaceId — идентификатор пространства, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства и нажмите кнопку ID.
- connectionId — идентификатор подключения, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства, на вкладке Подключение откройте страницу нужного подключения и нажмите кнопку ID.
- projectId — идентификатор проекта, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства, на вкладке Проекты откройте страницу нужного проекта и нажмите кнопку ID.
- text — текст поискового запроса. Вы можете задать слово, фразу или целое предложение. SpeechSense выполнит поиск заданной строки по текстовой расшифровке аудиозаписи или тексту чата.
- channelNumber — номер канала. Если параметр указан, поиск будет произведен только по текстовой расшифровке аудиозаписи или тексту чата для указанного канала.
  
  Нумерация каналов в подключениях для чатов:
  - 0 — канал оператора;
  - 1 — канал клиента;
  - 2 — канал бота.
  Нумерация каналов для аудио предустанавливается на уровне подключения и отличается от нумерации каналов для чатов.
Вы также можете использовать фильтры по параметрам вместе с полнотекстовым поиском. В таком случае в ответе вернутся только идентификаторы запросов, которые удовлетворяют и критериям полнотекстового поиска, и дополнительным фильтрам.

В запросе вы можете задать параметры сортировки результатов и количество результатов на одной странице. Подробнее о сортировке результатов и пагинации см. в разделе Параметры запроса.
Задайте API-ключ сервисного аккаунта:
```
export API_KEY=<API-ключ_сервисного_аккаунта>
```
Если вы используете IAM-токен, передайте его вместо API-ключа:
```
export IAM_TOKEN=<IAM-токен_сервисного_аккаунта>
```
Отправьте Search-запрос к API SpeechSense при помощи cURL:
```
curl -X POST https://rest-api.speechsense.yandexcloud.net/speechsense/v1/talks/search \
   -H "Content-Type: application/json" \
   -H "authorization: Api-Key ${API_KEY}" \
   -d @search.json
```
Где Api-Key — API-ключ для аутентификации. Если вы используете IAM-токен, укажите Bearer ${IAM_TOKEN} вместо Api-Key ${API_KEY}.

Идентификаторы диалогов, которые удовлетворяют условиям поиска, будут выведены в терминал в JSON-формате.

Пример тела запроса для полнотекстового поиска

Например, требуется найти все диалоги с техподдержкой провайдера, где оператор предлагал оформить заявку на выезд мастера. JSON-файл с параметрами запроса будет выглядеть так:

{
  "organizationId": "yc.organization****************",
  "spaceId": "f3fuclf1kufs********",
  "connectionId": "eag0u346n4hn********",
  "projectId": "eag9t3rm3o43********",
  "query": {
    "text": "выезд мастера",
    "channel_number": "0"
  },  
}

Результат выполнения запроса:

{
  "talk_ids": [
    "aud95sn63lra********"
  ],
  "talks_count":" 1",
  "next_page_token": ""
}

Где:

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

Пример тела запроса для полнотекстового поиска с фильтрацией по параметрам

Например, требуется найти все диалоги с техподдержкой провайдера в промежуток между 11:00 и 12:00 24 сентября 2024 года, где оператор предлагал оформить заявку на выезд мастера. JSON-файл с параметрами запроса будет выглядеть так:

{
  "organizationId": "yc.organization****************",
  "spaceId": "f3fuclf1kufs********",
  "connectionId": "eag0u346n4hn********",
  "projectId": "eag9t3rm3o43********",
  "query": {
    "text": "выезд мастера",
    "channel_number": "0"
  },
  "filters": [
    {
      "key": "userMeta.date",
      "date_range": {
        "from_value": "2024-09-24T11:00:00Z",
        "to_value": "2024-09-24T12:00:00Z"
      }
    }
  ],  
}

Результат выполнения запроса:

{
  "talk_ids": [
    "aud95sn63lra********"
  ],
  "talks_count":" 1",
  "next_page_token": ""
}

Где:

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

Фильтрация по параметрам

Создайте файл search.json и укажите в нем нужные идентификаторы и фильтры filters:
```
{
  "organizationId": "<идентификатор_организации>",
  "spaceId": "<идентификатор_пространства>",
  "connectionId": "<идентификатор_подключения>",
  "projectId": "<идентификатор_проекта>",
  "filters": [
    {
      "key": "<характеристика_диалога,_по_которой_производится_поиск>",
      "channelNumber": "<номер_канала>",

      // Укажите один или несколько фильтров
      "anyMatch": {
        "values": [
          "<поисковый_запрос>"
        ]
      },
      "intRange": {
        "fromValue": "<нижняя_граница>",
        "toValue": "<верхняя_граница>",
        "boundsInclusive": {
          "fromInclusive": "<включать_нижнюю_границу:_true_или_false>",
          "toInclusive": "<включать_верхнюю_границу:_true_или_false>"
        }
      },
      "doubleRange": {
        "fromValue": "<нижняя_граница>",
        "toValue": "<верхняя_граница>",
        "boundsInclusive": {
          "fromInclusive": "<включать_нижнюю_границу:_true_или_false>",
          "toInclusive": "<включать_верхнюю_границу:_true_или_false>"
        }
      },
      "dateRange": {
        "fromValue": "<нижняя_граница>",
        "toValue": "<верхняя_граница>",
        "boundsInclusive": {
          "fromInclusive": "<включать_нижнюю_границу:_true_или_false>",
          "toInclusive": "<включать_верхнюю_границу:_true_или_false>"
        }
      },
      "durationRange": {
        "fromValue": "<нижняя_граница>",
        "toValue": "<верхняя_граница>",
        "boundsInclusive": {
          "fromInclusive": "<включать_нижнюю_границу:_true_или_false>",
          "toInclusive": "<включать_верхнюю_границу:_true_или_false>"
        }
      },
      "booleanMatch": {
        "value": "<фильтр_по_значению_true_или_false>"
      }
    }
  ]
}
```
Где:
- organizationId — идентификатор организации, в которой выполняется запрос. Чтобы получить идентификатор, перейдите в сервис Cloud Center и нажмите кнопку под названием организации, в разделе .
- spaceId — идентификатор пространства, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства и нажмите кнопку ID.
- connectionId — идентификатор подключения, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства, на вкладке Подключение откройте страницу нужного подключения и нажмите кнопку ID.
- projectId — идентификатор проекта, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства, на вкладке Проекты откройте страницу нужного проекта и нажмите кнопку ID.
- key — характеристика диалога, по которой производится поиск. Возможные значения:
  - userMeta.<имя_поля> — поиск по метаданным пользователя. Где <имя_поля> — это поле метаданных пользователя, которое было указано при загрузке диалога. Пример: userMeta.date. Тип фильтра должен соответствовать типу поля метаданных (последний выбирается при создании подключения).
  - talk.classifiers.<имя_классификатора>.count — поиск по классификаторам.
  - talk.summarization.points.<идентификатор_вопроса> — поиск по резюме диалога. Идентификаторы вопросов из резюме диалога вы можете посмотреть в ответе Get-запроса.
  - talk.statistics.<название_статистики> — поиск по статистикам (только для аудио):
    - talk.statistics.duration_seconds — длительность диалога.
    - talk.statistics.simultaneous_silence.duration_seconds / talk.statistics.simultaneous_silence.ratio — одновременная тишина / доля одновременной тишины.
    - talk.statistics.simultaneous_speech.duration_seconds / talk.statistics.simultaneous_speech.ratio — одновременная речь / доля одновременной речи.
    - talk.statistics.interrupts.count — количество прерываний собеседника.
    - talk.statistics.phrases.count / talk.statistics.words.count / talk.statistics.letters.count — количество фраз / слов / символов в диалоге.
    - talk.statistics.words.count_per_second / talk.statistics.letters.count_per_second — количество слов / символов в секунду в указанном канале (канал указывается в фильтре).
    - talk.statistics.interrupts.duration_seconds — количество секунд прерывания указанным каналом в диалоге (канал указывается в фильтре).
- channelNumber — номер канала. Если параметр указан, фильтрация производится по метаданным, срабатываниям классификатора или статистикам, относящимся к данному каналу.
  
  Нумерация каналов в подключениях для чатов:
  - 0 — канал оператора;
  - 1 — канал клиента;
  - 2 — канал бота.
  Нумерация каналов для аудио предустанавливается на уровне подключения и отличается от нумерации каналов для чатов.
- anyMatch — определяет, входит ли значение из фильтра в поля метаданных, классификатора, статистики, резюме диалога. Например, фильтр с параметрами key = userMeta.ticket_id и values = [123, 345] найдет диалоги, у которых в поле метаданных ticket_id передано значение 123 или 345.
- intRange — проверяет, что целочисленное значение в поле, по которому производится поиск, лежит в диапазоне, указанном в фильтре. Подходит для поиска по классификаторам, полям метаданных целочисленного типа и статистикам со значениями целочисленного типа.
- doubleRange — то же самое, что intRange, но для чисел с плавающей точкой.
- dateRange — проверяет, что значение даты в поле, по которому производится поиск, лежит в диапазоне, заданном в фильтре.
- durationRange — проверяет, что длительность в поле, по которому производится поиск, лежит в диапазоне, указанном в фильтре.
- booleanMatch — проверяет, что поле типа boolean, по которому производится поиск, имеет заданное в фильтре значение (True или False). Подходит для поиска по резюме диалога и полям метаданных типа boolean.
Для каждого фильтра вы можете задать параметр boundsInclusive. Он определяет, включать ли в поиск границы диапазона:
- fromInclusive — нижняя граница;
- toInclusive — верхняя граница.
В запросе вы также можете задать параметры сортировки результатов и количество результатов на одной странице. Подробнее о сортировке результатов и пагинации см. в разделе Параметры запроса.
Задайте API-ключ сервисного аккаунта:
```
export API_KEY=<API-ключ_сервисного_аккаунта>
```
Если вы используете IAM-токен, передайте его вместо API-ключа:
```
export IAM_TOKEN=<IAM-токен_сервисного_аккаунта>
```
Отправьте Search-запрос к API SpeechSense при помощи cURL:
```
curl -X POST https://rest-api.speechsense.yandexcloud.net/speechsense/v1/talks/search \
   -H "Content-Type: application/json" \
   -H "authorization: Api-Key ${API_KEY}" \
   -d @search.json
```
Где Api-Key — API-ключ для аутентификации. Если вы используете IAM-токен, укажите Bearer ${IAM_TOKEN} вместо Api-Key ${API_KEY}.

Идентификаторы диалогов, которые удовлетворяют условиям поиска, будут выведены в терминал в JSON-формате. будут выведены в терминал в JSON-формате.

Пример тела запроса для фильтрации по отдельным параметрам

Например, требуется найти все диалоги с техподдержкой провайдера в промежуток между 11:00 и 12:00 24 сентября 2024 года. JSON-файл с параметрами запроса будет выглядеть так:

{
  "organizationId": "yc.organization****************",
  "spaceId": "f3fuclf1kufs********",
  "connectionId": "eag0u346n4hn********",
  "projectId": "eag9t3rm3o43********",
  "filters": [
    {
      "key": "userMeta.date",
      "date_range": {
        "from_value": "2024-09-24T11:00:00Z",
        "to_value": "2024-09-24T12:00:00Z"
      }
    }
  ]
}

Результат выполнения запроса:

{
  "talk_ids": [
    "aud95sn63lra********"
  ],
  "talks_count": "1",
  "next_page_token": ""
}

Где:

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

Получить информацию о диалоге

Создайте в папке файл get.json с параметрами для получения нужного диалога:
```
{
  "organizationId": "<идентификатор_организации>",
  "spaceId": "<идентификатор_пространства>",
  "connectionId": "<идентификатор_подключения>",
  "projectId": "<идентификатор_проекта>",
  "talk_ids": [
    "<идентификатор_диалога>"
  ],
  "results_mask": {
    "paths": [
      "<ключи_запрашиваемых_полей>"
    ]
  }
}
```
Где:
- organizationId — идентификатор организации, в которой выполняется запрос. Чтобы получить идентификатор, перейдите в сервис Cloud Center и нажмите кнопку под названием организации, в разделе .
- spaceId — идентификатор пространства, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства и нажмите кнопку ID.
- connectionId — идентификатор подключения, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства, на вкладке Подключение откройте страницу нужного подключения и нажмите кнопку ID.
- projectId — идентификатор проекта, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства, на вкладке Проекты откройте страницу нужного проекта и нажмите кнопку ID.
- paths — список полей, которые вы хотите получить.
Выполните Get-запрос к API SpeechSense при помощи cURL:
```
curl -X POST https://rest-api.speechsense.yandexcloud.net/speechsense/v1/talks/get \
   -H "Content-Type: application/json" \
   -H "authorization: Api-Key ${API_KEY}" \
   -d @get.json
```
Где Api-Key — API-ключ для аутентификации. Если вы используете IAM-токен, укажите Bearer ${IAM_TOKEN} вместо Api-Key ${API_KEY}.

Результаты поиска будут выведены в терминал в JSON-формате.

Пример тела запроса на получение информации о диалоге

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

JSON-файл с параметрами запроса будет выглядеть так:

{
  "organizationId": "yc.organization****************",
  "spaceId": "f3fuclf1kufs********",
  "connectionId": "eag0u346n4hn********",
  "projectId": "eag9t3rm3o43********",
  "talk_ids": ["aud95sn63lra********"],
  "results_mask": {
    "paths": ["points"]
  }
}

Результат выполнения запроса

{
  "talk": [
    {
      "id": "aud95sn63lra********",
      "organization_id": "yc.organization****************",
      "space_id": "f3fuclf1kufs********",
      "connection_id": "eag0u346n4hn********",
      "project_ids": [
        "eag9t3rm3o43********"
      ],
      "created_by": "ajeugoqa16o5********",
      "created_at": "2024-09-24T08:53:09.932Z",
      "modified_by": "CLASSIFIER",
      "modified_at": "2024-09-24T18:06:08.299Z",
      "talk_fields": [
        {
          "name": "operator_name",
          "value": "Оператор",
          "type": "FIELD_TYPE_STRING"
        },
        {
          "name": "operator_id",
          "value": "operator_id",
          "type": "FIELD_TYPE_STRING"
        },
        {
          "name": "client_name",
          "value": "Клиент",
          "type": "FIELD_TYPE_STRING"
        },
        {
          "name": "client_id",
          "value": "customer_id",
          "type": "FIELD_TYPE_STRING"
        },
        {
          "name": "bot_name",
          "value": "Бот",
          "type": "FIELD_TYPE_STRING"
        },
        {
          "name": "bot_id",
          "value": "bot_id",
          "type": "FIELD_TYPE_STRING"
        },
        {
          "name": "date",
          "value": "2024-09-24T11:11:11.111Z",
          "type": "FIELD_TYPE_DATE"
        },
        {
          "name": "direction_outgoing",
          "value": "true",
          "type": "FIELD_TYPE_BOOLEAN"
        },
        {
          "name": "language",
          "value": "Russian",
          "type": "FIELD_TYPE_STRING"
        }
      ],
      "transcription": null,
      "speech_statistics": null,
      "silence_statistics": null,
      "interrupts_statistics": null,
      "conversation_statistics": null,
      "points": {
        "quiz": [
          {
            "request": "1. Оператор был вежливым?",
            "response": "1. Да",
            "id": "1"
          },
          {
            "request": "2. Оператор был раздражен?",
            "response": "2. Нет",
            "id": "2"
          },
          {
            "request": "3. Оператор был вовлечен в диалог?",
            "response": "3. Нет",
            "id": "3"
          },
          {
            "request": "4. Оператор был эмпатичным?",
            "response": "4. Да",
            "id": "4"
          },
          {
            "request": "5. Оператор хамил?",
            "response": "5. Нет",
            "id": "5"
          },
          {
            "request": "6. Оператор решил проблему клиента?",
            "response": "6. Нет",
            "id": "6"
          },
          {
            "request": "7. Оператор был уверенным?",
            "response": "7. Да",
            "id": "7"
          },
          {
            "request": "8. Клиент ушел раздраженным?",
            "response": "8. Нет",
            "id": "8"
          },
          {
            "request": "9. Клиент остался доволен?",
            "response": "9. Да",
            "id": "9"
          },
          {
            "request": "10. Клиент хамил?",
            "response": "10. Нет",
            "id": "10"
          }
        ]
      },
      "text_classifiers": null
    }
  ]
}

Параметры запросов

Search-запрос

Полнотекстовый поиск

{
  "organizationId": "<идентификатор_организации>",
  "spaceId": "<идентификатор_пространства>",
  "connectionId": "<идентификатор_подключения>",
  "projectId": "<идентификатор_проекта>",
  "query": {
    "text": "<поисковый_запрос>",
    "channelNumber": "<номер_канала>"
  },
  "sort_data": {
    "fields": [{  
      "field": "<характеристика_диалога,_по_которой_производится_поиск>",
      "order": "<порядок_сортировки:_по_возрастанию_или_убыванию>",
      "position": "<приоритет_поля_сортировки>"
    }]
  },
  "pageSize": "<количество_документов_на_странице>",
  "pageToken": "<токен_следующей_страницы_с_результатами_поиска>"
}

Где:

organizationId — идентификатор организации, в которой выполняется запрос. Чтобы получить идентификатор, перейдите в сервис Cloud Center и нажмите кнопку под названием организации, в разделе .
spaceId — идентификатор пространства, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства и нажмите кнопку ID.
connectionId — идентификатор подключения, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства, на вкладке Подключение откройте страницу нужного подключения и нажмите кнопку ID.
projectId — идентификатор проекта, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства, на вкладке Проекты откройте страницу нужного проекта и нажмите кнопку ID.

query — тело запроса полнотекстового поиска. Поддерживает следующие параметры:
- text — текст поискового запроса. Вы можете задать слово, фразу или целое предложение. SpeechSense выполнит поиск заданной строки по текстовой расшифровке аудиозаписи или тексту чата.
- channelNumber — номер канала. Если параметр указан, поиск будет произведен только по текстовой расшифровке аудиозаписи или тексту чата для указанного канала.
  
  Нумерация каналов в подключениях для чатов:
  - 0 — канал оператора;
  - 1 — канал клиента;
  - 2 — канал бота.
  Нумерация каналов для аудио предустанавливается на уровне подключения и отличается от нумерации каналов для чатов.
sort_data — параметры сортировки данных в ответе на запрос.
- fields — список характеристик диалога, по которым производится сортировка. Поддерживает следующие параметры:
  - field — характеристика, диалога, по которой производится поиск.
  - order — порядок сортировки: по возрастанию или убыванию.
  - position — приоритет поля сортировки (при сортировке по нескольким характеристикам диалога одновременно).
pageSize — количество документов на странице.
pageToken — токен следующей страницы с результатами поискового запроса.
Если результаты запроса разделены на несколько страниц, каждая страница имеет свой токен. В ответе на каждый поисковый запрос содержится токен следующей страницы next_page_token (если она существует). Вставьте его в параметр pageToken поискового запроса, чтобы получить следующую страницу с результатами поиска.

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

Фильтрация по параметрам

{
  "organizationId": "<идентификатор_организации>",
  "spaceId": "<идентификатор_пространства>",
  "connectionId": "<идентификатор_подключения>",
  "projectId": "<идентификатор_проекта>",
  "filters": [
    {
      "key": "<характеристика_диалога,_по_которой_производится_поиск>",
      "channelNumber": "<номер_канала>",

      // Укажите один или несколько фильтров
      "anyMatch": {
        "values": [
          "<поисковый_запрос>"
        ]
      },
      "intRange": {
        "fromValue": "<нижняя_граница>",
        "toValue": "<верхняя_граница>",
        "boundsInclusive": {
          "fromInclusive": "<включать_нижнюю_границу:_true_или_false>",
          "toInclusive": "<включать_верхнюю_границу:_true_или_false>"
        }
      },
      "doubleRange": {
        "fromValue": "<нижняя_граница>",
        "toValue": "<верхняя_граница>",
        "boundsInclusive": {
          "fromInclusive": "<включать_нижнюю_границу:_true_или_false>",
          "toInclusive": "<включать_верхнюю_границу:_true_или_false>"
        }
      },
      "dateRange": {
        "fromValue": "<нижняя_граница>",
        "toValue": "<верхняя_граница>",
        "boundsInclusive": {
          "fromInclusive": "<включать_нижнюю_границу:_true_или_false>",
          "toInclusive": "<включать_верхнюю_границу:_true_или_false>"
        }
      },
      "durationRange": {
        "fromValue": "<нижняя_граница>",
        "toValue": "<верхняя_граница>",
        "boundsInclusive": {
          "fromInclusive": "<включать_нижнюю_границу:_true_или_false>",
          "toInclusive": "<включать_верхнюю_границу:_true_или_false>"
        }
      },
      "booleanMatch": {
        "value": "<фильтр_по_значению_true_или_false>"
      }
    }
  ],
  "sort_data": {
    "fields": [{  
      "field": "<характеристика_диалога,_по_которой_производится_поиск>",
      "order": "<порядок_сортировки:_по_возрастанию_или_убыванию>",
      "position": "<приоритет_поля_сортировки>"
    }]
  },
  "pageSize": "<количество_документов_на_странице>",
  "pageToken": "<токен_следующей_страницы_с_результатами_поиска>"
}

organizationId — идентификатор организации, в которой выполняется запрос. Чтобы получить идентификатор, перейдите в сервис Cloud Center и нажмите кнопку под названием организации, в разделе .
spaceId — идентификатор пространства, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства и нажмите кнопку ID.
connectionId — идентификатор подключения, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства, на вкладке Подключение откройте страницу нужного подключения и нажмите кнопку ID.
projectId — идентификатор проекта, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства, на вкладке Проекты откройте страницу нужного проекта и нажмите кнопку ID.

filters — тело запроса на фильтрацию по отдельным параметрам. Поддерживает следующие параметры:
- key — характеристика диалога, по которой производится поиск. Возможные значения:
  - userMeta.<имя_поля> — поиск по метаданным пользователя. Где <имя_поля> — это поле метаданных пользователя, которое было указано при загрузке диалога. Пример: userMeta.date. Тип фильтра должен соответствовать типу поля метаданных (последний выбирается при создании подключения).
  - talk.classifiers.<имя_классификатора>.count — поиск по классификаторам.
  - talk.summarization.points.<идентификатор_вопроса> — поиск по резюме диалога. Идентификаторы вопросов из резюме диалога вы можете посмотреть в ответе Get-запроса.
  - talk.statistics.<название_статистики> — поиск по статистикам (только для аудио):
    - talk.statistics.duration_seconds — длительность диалога.
    - talk.statistics.simultaneous_silence.duration_seconds / talk.statistics.simultaneous_silence.ratio — одновременная тишина / доля одновременной тишины.
    - talk.statistics.simultaneous_speech.duration_seconds / talk.statistics.simultaneous_speech.ratio — одновременная речь / доля одновременной речи.
    - talk.statistics.interrupts.count — количество прерываний собеседника.
    - talk.statistics.phrases.count / talk.statistics.words.count / talk.statistics.letters.count — количество фраз / слов / символов в диалоге.
    - talk.statistics.words.count_per_second / talk.statistics.letters.count_per_second — количество слов / символов в секунду в указанном канале (канал указывается в фильтре).
    - talk.statistics.interrupts.duration_seconds — количество секунд прерывания указанным каналом в диалоге (канал указывается в фильтре).
- channelNumber — номер канала. Если параметр указан, фильтрация производится по метаданным, срабатываниям классификатора или статистикам, относящимся к данному каналу.
  
  Нумерация каналов в подключениях для чатов:
  - 0 — канал оператора;
  - 1 — канал клиента;
  - 2 — канал бота.
  Нумерация каналов для аудио предустанавливается на уровне подключения и отличается от нумерации каналов для чатов.
Доступны следующие фильтры:
- anyMatch — определяет, входит ли значение из фильтра в поля метаданных, классификатора, статистики, резюме диалога. Например, фильтр с параметрами key = userMeta.ticket_id и values = [123, 345] найдет диалоги, у которых в поле метаданных ticket_id передано значение 123 или 345.
- intRange — проверяет, что целочисленное значение в поле, по которому производится поиск, лежит в диапазоне, указанном в фильтре. Подходит для поиска по классификаторам, полям метаданных целочисленного типа и статистикам со значениями целочисленного типа.
- doubleRange — то же самое, что intRange, но для чисел с плавающей точкой.
- dateRange — проверяет, что значение даты в поле, по которому производится поиск, лежит в диапазоне, заданном в фильтре.
- durationRange — проверяет, что длительность в поле, по которому производится поиск, лежит в диапазоне, указанном в фильтре.
- booleanMatch — проверяет, что поле типа boolean, по которому производится поиск, имеет заданное в фильтре значение (True или False). Подходит для поиска по резюме диалога и полям метаданных типа boolean.
Для каждого фильтра вы можете задать параметр boundsInclusive. Он определяет, включать ли в поиск границы диапазона:
- fromInclusive — нижняя граница;
- toInclusive — верхняя граница.
sort_data — параметры сортировки данных в ответе на запрос.
- fields — список характеристик диалога, по которым производится сортировка. Поддерживает следующие параметры:
  - field — характеристика, диалога, по которой производится поиск.
  - order — порядок сортировки: по возрастанию или убыванию.
  - position — приоритет поля сортировки (при сортировке по нескольким характеристикам диалога одновременно).
pageSize — количество документов на странице.
pageToken — токен следующей страницы с результатами поискового запроса.
Если результаты запроса разделены на несколько страниц, каждая страница имеет свой токен. В ответе на каждый поисковый запрос содержится токен следующей страницы next_page_token (если она существует). Вставьте его в параметр pageToken поискового запроса, чтобы получить следующую страницу с результатами поиска.

Подробнее о параметрах Search-запроса см. в справочнике API.

Get-запрос

{
  "organizationId": "<идентификатор_организации>",
  "spaceId": "<идентификатор_пространства>",
  "connectionId": "<идентификатор_подключения>",
  "projectId": "<идентификатор_проекта>",
  "talk_ids": [
    "<идентификатор_диалога>"
  ],
  "results_mask": {
    "paths": [
      "<ключи_запрашиваемых_полей>"
    ]
  }
}

Где:

organizationId — идентификатор организации, в которой выполняется запрос. Чтобы получить идентификатор, перейдите в сервис Cloud Center и нажмите кнопку под названием организации, в разделе .
spaceId — идентификатор пространства, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства и нажмите кнопку ID.
connectionId — идентификатор подключения, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства, на вкладке Подключение откройте страницу нужного подключения и нажмите кнопку ID.
projectId — идентификатор проекта, в котором выполняется запрос. Чтобы получить идентификатор, перейдите в сервис SpeechSense, откройте страницу нужного пространства, на вкладке Проекты откройте страницу нужного проекта и нажмите кнопку ID.

talk_ids — идентификаторы диалогов, информацию о которых вы хотите получить. Чтобы узнать идентификаторы диалогов, используйте Search-запрос.
results_mask — маска результатов. Если этот параметр не передан, вернется вся информация о диалоге, а если параметр передан с пустым списом paths, вернется только базовая информация о диалоге: идентификаторы проекта, подключения и пространства, когда и кем создан и изменен, а также метаданные, добавленные при загрузке диалога. Чтобы выгрузить отдельные поля с данными, передайте в маске ключи нужных полей в списке paths:
- transcription — текстовая расшифровка аудиозаписи или текстовые сообщения из чата.
- speech_statistics — статистика речи.
- silence_statistics — статистика пауз в диалоге.
- interrupts_statistics — статистика прерываний собеседника.
- conversation_statistics — статистика диалога.
- points — резюме диалога.
- text_classifiers — статистика по классификаторам (тегам).

Подробнее о параметрах Get-запроса см. в справочнике API.

Поиск данных через REST API

Перед началом работыПеред началом работы

Полнотекстовый поискПолнотекстовый поиск

Пример тела запроса для полнотекстового поискаПример тела запроса для полнотекстового поиска

Пример тела запроса для полнотекстового поиска с фильтрацией по параметрамПример тела запроса для полнотекстового поиска с фильтрацией по параметрам

Фильтрация по параметрамФильтрация по параметрам

Пример тела запроса для фильтрации по отдельным параметрамПример тела запроса для фильтрации по отдельным параметрам

Получить информацию о диалогеПолучить информацию о диалоге

Пример тела запроса на получение информации о диалогеПример тела запроса на получение информации о диалоге

Параметры запросовПараметры запросов

Search-запросSearch-запрос

Полнотекстовый поискПолнотекстовый поиск

Фильтрация по параметрамФильтрация по параметрам

Get-запросGet-запрос

Была ли статья полезна?

Перед началом работы

Полнотекстовый поиск

Пример тела запроса для полнотекстового поиска

Пример тела запроса для полнотекстового поиска с фильтрацией по параметрам

Фильтрация по параметрам

Пример тела запроса для фильтрации по отдельным параметрам

Получить информацию о диалоге

Пример тела запроса на получение информации о диалоге

Параметры запросов

Search-запрос

Полнотекстовый поиск

Фильтрация по параметрам

Get-запрос