Связаться с намиПодключиться

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

Статья создана
Обновлена 2 декабря 2024 г.

Фильтрация по параметрам позволяет находить диалоги, соответствующие заданным условиям. Запрос возвращает идентификаторы подходящих диалогов. Подробнее о том, как получить информацию о диалоге по его идентификатору, см. в инструкции.

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

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

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

  1. В консоли управления создайте сервисный аккаунт.

  2. Добавьте сервисный аккаунт в пространство с ролью Data viewer. Это позволит сервисному аккаунту работать с данными в SpeechSense.

  3. Чтобы аутентифицироваться в API Yandex Cloud, создайте API-ключ или IAM-токен для сервисного аккаунта.

  4. Загрузите аудиозаписи или чаты в SpeechSense.

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

  1. Создайте файл 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>"
      }
    }
  ],
  "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.<идентификатор_вопроса> — фильтрация по резюме диалога. Идентификаторы вопросов из резюме диалога вы можете получить вместе с данными о диалоге.

        • 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 — количество слов в секунду в канале, который указывается в параметре channelNumber.
          • talk.statistics.letters.count_per_second — количество символов в секунду в канале, который указывается в параметре channelNumber.
          • talk.statistics.interrupts.duration_seconds — длительность прерываний одним из участников речи другого участника, в секундах. Канал прерывающего участника указывается в параметре channelNumber.

      • channelNumber — номер канала. Если номер указан, фильтр применяется к метаданным, срабатываниям классификатора или статистикам, относящимся к этому каналу.

        Нумерация каналов в подключениях для чатов:

        • 0 — канал оператора;
        • 1 — канал клиента;
        • 2 — канал бота.

        Нумерация каналов для аудио предустанавливается на уровне подключения и отличается от нумерации каналов для чатов.

      Доступны следующие фильтры:

      • anyMatch — определяет, встречается ли значение из фильтра в метаданных, классификаторах, статистиках, резюме диалога. Например, фильтр с параметрами key = userMeta.ticket_id и values = [123, 345] вернет диалоги, у которых в поле метаданных ticket_id передано значение 123 или 345.
      • intRange — проверяет, что заданное целочисленное значение попадает в диапазон, указанный в фильтре. Подходит для фильтрации по классификаторам, полям метаданных целочисленного типа и статистикам со значениями целочисленного типа.
      • doubleRange — проверяет, что заданное число с плавающей точкой попадает в диапазон, указанный в фильтре. Подходит для фильтрации по классификаторам, полям метаданных и статистикам со значениями с плавающей точкой.
      • dateRange — проверяет, что заданное значение даты попадает в диапазон, указанный в фильтре.
      • durationRange — проверяет, что заданная длительность попадает в диапазон, указанный в фильтре. Подходит для фильтрации по длительности диалога, прерываний, одновременной речи или тишины.
      • booleanMatch — проверяет, что заданное значение типа boolean соответствует значению в фильтре (True или False). Подходит для фильтрации по резюме диалога и полям метаданных типа boolean.

      Для каждого фильтра вы можете задать параметр boundsInclusive. Он определяет, включать ли в фильтр границы диапазона:

      • fromInclusive — нижняя граница;
      • toInclusive — верхняя граница.

    • sort_data — параметры сортировки данных в ответе на запрос.

      • fields — список характеристик диалога, по которым производится сортировка. Поддерживает следующие параметры:
        • field — характеристика диалога, по которой производится сортировка.
        • order — порядок сортировки: по возрастанию или убыванию.
        • position — приоритет поля сортировки (при сортировке по нескольким характеристикам диалога одновременно).

    • pageSize — количество документов на странице.

    • pageToken — токен следующей страницы с результатами запроса. 
      Если результаты запроса разделены на несколько страниц, каждая страница имеет свой токен. В ответе на каждый запрос содержится токен следующей страницы next_page_token (если она существует). Вставьте его в параметр pageToken запроса, чтобы получить следующую страницу с результатами.

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

  2. Задайте API-ключ сервисного аккаунта:

    export API_KEY=<API-ключ_сервисного_аккаунта>

    Если вы используете IAM-токен, передайте его вместо API-ключа:

    export IAM_TOKEN=<IAM-токен_сервисного_аккаунта>

  3. Отправьте 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-формате.

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

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