Стандартизация пакета записей с контактными данными

Данная команда позволяет обрабатывать пакет (группу) из нескольких несвязанных друг с другом записей. Каждая запись пакета обрабатывается независимо от остальных записей. Сама обработка выполняется по аналогии с тем, как если бы для этого использовалась команда cleanse/record.

Пакетная обработка может быть полезна в ситуации, когда на стороне пользовательского приложения имеется база данных с контактными данными о клиентах, которые необходимо обработать и привести в порядок. В этом случае данные о каждом клиенте объединяются в запись, как это описано в документации к команде cleanse/record по следующей ссылке cleanse/record#Basic. Однако вместо того, чтобы отсылать каждую запись на обработку в виде отдельного запроса cleanse/record, записи можно группировать в пакеты и обрабатывать командой cleanse/chunk.

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

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

Принципы использования команды cleanse/chunk

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

1. Полагается, что приложение пользователя имеет большой файл или базу данных с контактной информацией, стандартизацию которой необходимо выполнить.
2. Приложение пользователя итеративно извлекает из обрабатываемой базы или файла порции контактных данных. Рекомендуется использовать порцию, содержащую не более 50 записей.
3. Извлеченную порцию приложение оформляет в виде пакета и отправляет сервису на обработку, используя для этого данную команду cleanse/chunk.
4. Получив ответ с результатом стандартизации пакета, приложение выполняет необходимые действия с этим результатом, после чего отсылает сервису на обработку следующую порцию.

Пакет представляет собой массив из нескольких записей, каждая из которых в общем случае представляет собой структуру из нескольких элементов разного типа. Поэтому, так же, как и в случае с использованием команды cleanse/record, запрос передается сервису в параметре query не в виде простой строки, а в виде JSON-текста или XML-сообщения.

Чтобы подсказать сервису, в каком именно формате (JSON или XML) ему передается на обработку пакет, нужно использовать параметр input со значениями input=json или input=xml.

Запрос на обработку пакета контактных данных в формате JSON

Ниже приведен пример запроса при передаче на обработку пакета в формате JSON.

{
  "records":
  [
    {
      "id": "1",
      "items": 
      [
        { 
          "type": "address", 
          "role": "рабочий адрес", 
          "body": "ивановка, ул. строителей д.1" 
        },
        { 
          "type": "phone", 
          "role": "рабочий телефон", 
          "body": "533-61-00" 
        }
      ]
    },
    {
      "id": "2",
      "items": 
      [
        { 
          "type": "address", 
          "role": "рабочий адрес", 
          "body": "Москва, ул. Ткацкая д.5" 
        },
        { 
          "type": "phone", 
          "role": "рабочий телефон", 
          "body": "1663050" 
        }
      ]
    }
  ]
}

В приведенном примере пакет, подлежащий обработке, содержит две записи с идентификаторами "1" и "2" соответственно. Обе записи содержат почтовый адрес и телефонный номер.

Записи перечислены в рамках массива records. Каждый элемент этого массива соответствует одной обрабатываемой записи пакета. Структура каждой записи полностью аналогична структуре, используемой для оформления одной записи при передаче ее на обработку командой cleanse/record. Описание данной структуры в формате JSON приведено по следующей ссылке: cleanse/record#JSON-record

Запрос на обработку пакета контактных данных в формате XML

Ниже приведен пример запроса при передаче на обработку пакета в формате XML.

<ProcessChunkRequest>

  <record id="1">
    <item type="address" role="рабочий адрес">
      ивановка, ул. строителей д.1
    </item>
    <item type="phone" role="рабочий телефон">533-61-00</item>
  </record>
  
  <record id="2">
    <item type="address" role="рабочий адрес">
      Москва, ул. Ткацкая д.5
    </item>
    <item type="phone" role="рабочий телефон">1663050</item>
  </record>
  
</ProcessChunkRequest>

Запрос в формате XML представляет собой документ со следующими дочерними XML-элементами.

• record – XML-элемент, соответствующий одной обрабатываемой записи пакета. Поскольку команда cleanse/chunk предназначена для обработки пакета из нескольких записей, то обычно XML-элементов record должно быть несколько по числу записей пакета. Список из всех XML-элементов record эквивалентен JSON-массиву records при использовании запроса в формате JSON. Структура каждой записи полностью аналогична структуре, используемой для оформления одной записи при передаче ее на обработку командой cleanse/record. Описание данной структуры в формате XML приведено по следующей ссылке: cleanse/record#XML-record.

Передача запроса

Запрос в виде JSON-строки или XML-сообщения передается сервису в рамках параметра query. Данный параметр может передаваться как методом GET в рамках URL запроса, так и методом POST в рамках HTTP-тела запроса. В обоих случаях строка с запросом должна быть закодирована с использованием URL-encoding.

Пример простого запроса по обработке пакета контактных данных

Приведенный ниже запрос отсылает сервису на обработку пакет записей, представленный выше в формате JSON. При этом используется минимальное количество параметров и опций.

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

• user=demotoken - сообщает сервису API-токен пользователя. При отправке реального запроса вместо значения demotoken нужно подставить токен из личного кабинета.
• output=json - сообщает сервису о том, что необходимо вернуть ответ в формате JSON.
• input=json - сообщает сервису, что исходный запрос передается в формате JSON.
• query=%7B%0D%0A%20%20%22records%22%3A%0D%0A%20%20%5B%0D%20...%0D%0A%20%20%5D%0D%0A%7D - закодированный с использованием URL-encoding исходный JSON-текст обрабатываемого пакета. Для компактности здесь приведено только начало и конец тела запроса, остальная часть запроса заменена многоточием.

Параметры команды

Обязательные параметры для выполнения запроса.

• https://ahunter.ru/site/cleanse/chunk - URL-команды.
• user=API-токен - API-токен пользователя из личного кабинета.
• output=json или output=xml - формат, в котором требуется вернуть результат обработки.
• input=json или input=xml - формат, в котором запрос передается на обработку.
• query=строка запроса - строка, содержащая JSON или XML текст обрабатываемого пакета.

В рамках данной API-команды также доступны все опциональный параметры, применимые к команде обработки одной записи cleanse/record. Описание этих параметров приведено по следующей ссылке: cleanse/record#OptionalParams.

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

Приведенный ниже запрос отсылает сервису на обработку пакет, представленный ранее в формате XML, с дополнительными параметрами.

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

• user=demotoken - сообщает сервису API-токен пользователя.
• output=json|pretty|ageo - сообщает сервису о том, что необходимо вернуть ответ в формате JSON, отформатировав его "красиво". При этом у сервиса дополнительно запрашиваются географические координаты для каждого почтового адреса обработанного пакета.
• input=xml - сообщает сервису о том, что пакет, передаваемый для обработки, представлен в формате XML.
• addresslim=3 - сообщает сервису, что в случае многозначного распознавания адресов, содержащихся в пакете, следует вернуть первые три варианта, наиболее соответствующие обработанному элементу.
• phonelim=1 - сообщает сервису, что в случае многозначного распознавания телефонов, содержащихся в записях пакета, следует вернуть только один вариант, наиболее соответствующий обработанному элементу.
• personlim=1 - сообщает сервису, что в случае многозначного распознавания элементов пакета, содержащих ФИО, следует вернуть только один вариант, наиболее соответствующий обработанному элементу.
• query=%3CProcessChunkRequest%3E%0D%0A ... %0A%3C%2FProcessChunkRequest%3 - закодированный с использованием URL-encoding исходный XML-текст пакета, подлежащего обработке. Для компактности здесь приведено только начало и конец тела запроса, остальная часть запроса заменена многоточием.

Результат запроса: стандартизованный пакет контактных данных в формате JSON

Ниже приведен ответ сервиса с результатом обработки пакета, представленного в качестве примера ранее. Результирующий JSON-ответ получен с использованием опции output=json|pretty, позволяющей выполнить "красивое" форматирование JSON-текста.

{
  "records" : [
    {
      "id" : "1",
      "items" : [
        {
          "body" : "ивановка, ул. строителей д. 1",
          "result" : { ... результат обработки почтового адреса ... },
          "role" : "рабочий адрес",
          "type" : "address"
        },
        {
          "body" : "533-61-00",
          "result" : { ... результат обработки телефонного номера ... },
          "role" : "рабочий телефон",
          "type" : "phone"
        }
      ]
    },
    {
      "id" : "2",
      "items" : [
        {
          "body" : "Москва, ул. Ткацкая д.5",
          "result" : { ... результат обработки почтового адреса ... },
          "role" : "рабочий адрес",
          "type" : "address"
        },
        {
          "body" : "1663050",
          "result" : { ... результат обработки телефонного номера ...  },
          "role" : "рабочий телефон",
          "type" : "phone"
        }
      ]
    }
  ],
  "request_process_time" : 50
}

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

Ответ сервиса повторяет структуру исходного пакета - в нем так же присутствует массив записей records. В рамках каждого элемента каждой записи массива records добавлен результат обработки посредством JSON-объекта result. Результат обработки каждой записи пакета аналогичен результату обработки единичной записи, возвращаемому командой cleanse/record. Данное описание доступно по следующей ссылке cleanse/record#JSON-record_result.

Результат запроса: стандартизованный пакет контактных данных в формате XML

Возвращаемые в XML-ответе элементы имеют аналогичное назначение JSON-элементам, описанным выше. Для получения ответа в формате XML необходимо в исходном запросе использовать значение параметра output=xml.

Ниже приведен XML-ответ сервиса с результатом обработки пакета, представленного в начале данной документации.

<ProcessChunkResult>
  <record id="1">
    <item type="address" role="рабочий адрес">
      <Address>
        ... вариант стандартизации адреса ...
      </Address>
      <CheckInfo>
        ... сводная информация о результате обработки адреса ...
      </CheckInfo>
      <BestPhone role="рабочий телефон" item="1"/>
    </item>
    <item type="phone" role="рабочий телефон">
      <Phone type="fixed" verified="1">
        ... вариант стандартизации телефона ...
      </Phone>
      <CheckInfo>
        ... сводная информация о результате обработки телефона ...
      </CheckInfo>
      <BestAddress role="рабочий адрес" item="0"/>
    </item>
  </record>
  <record id="2">
    <item type="address" role="рабочий адрес">
      <Address>
        ... вариант стандартизации адреса ...
      </Address>
      <CheckInfo>
        ... сводная информация о результате обработки адреса ...
      </CheckInfo>
      <BestPhone role="рабочий телефон" item="1"/>
    </item>
    <item type="phone" role="рабочий телефон">
      <Phone type="fixed" verified="1">
        ... вариант стандартизации телефона ...
      </Phone>
      <CheckInfo>
        ... сводная информация о результате обработки телефона ...
      </CheckInfo>
      <BestAddress role="рабочий адрес" item="0"/>
    </item>
  </record>
</ProcessChunkResult>

Как и при описании JSON-ответа сервиса, в приведенном XML-ответе для простоты изложения результаты стандартизации элементов записей пакета заменены комментариями типа ...вариант стандартизации....

XML-ответ, по аналогии с JSON-ответом, повторяет структуру исходного пакета. Ответ сервиса, также как и исходный запрос, представлен списком дочерних XML-элементов record, каждый из которых соответствует записи пакета.

В рамках каждого элемента каждой записи сервис возвращает результат его стандартизации. Результат обработки каждой записи пакета аналогичен результату обработки единичной записи, возвращаемому командой cleanse/record. Данное описание доступно по следующей ссылке cleanse/record#XML-record_result.