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

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

Дополнительно в рамках данной команды вместе с пакетом обрабатываемых записей может передаваться адресный фильтр, заданный в явном виде. Данная черта отличает команду cleanse/chunk от всех остальных API-команд, воспринимающих адресный фильтр лишь в виде идентификатора, ссылающегося на заранее подготовленный фильтр в разделе "Фильтры адресов" личного кабинета пользователя. Это может быть полезно в случае, если приложение пользователя может формировать адресные фильтры автоматически на лету, например, на основе имеющейся априорной информации о региональной принадлежности обрабатываемых адресных данных.

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

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

{
  "filters":
  {
    "priority": [ { "code": "24", "address": "Красноярский край" } ]
  },
  
  "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" соответственно. Обе записи содержат почтовый адрес и телефонный номер. Кроме записей в запросе передается приоритетный адресный фильтр, указывающий сервису, что в случае многозначного распознавания адресов приоритет следует отдавать адресам из Красноярского края.

Ниже приведено назначение всех элементов приведенного запроса в формате JSON.

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

JSON-объект filters: опциональный фильтр почтовых адресов

JSON-объект filters позволяет задать настройки адресного фильтра, применимого к каждому почтовому адресу, обрабатываемому в рамках пакета. Данный JSON-объект не является обязательным и в рамках запроса может не передаваться. Существуют следующие виды фильтров.

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

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

{
  "priority": 
  [ 
    { "address": "Москва", "level": "Region" } 
  ],
  
  "required": 
  [ 
    { "code": "77", "address": "г Москва" },
    { "code": "24", "address": "Красноярский край" },
    { "address": "обл Иркутская" },
    { "address": "Тюменская", "level": "Region" }
  ],
  
  "rejector":
  [
    { "address": "Тюменская область", "level": "Region" },
    { "address": "Иркутская", "level": "Region" }
  ]
}

Описание каждого из трех типов фильтров в рамках JSON-объекта filters выполняется с помощью следующих дочерних JSON-элементов.

  • priority – JSON-массив, задающий перечень адресных объектов приоритетного фильтра.
  • required - JSON-массив, задающий перечень адресных объектов обязующего фильтра.
  • rejector - JSON-массив, задающий перечень адресных объектов режекторного фильтра.

Каждый элемент этих массивов представляет собой JSON-объект, соответствующий одному адресному объекту. Описание этих объектов приведено в следующем подразделе.

Фильтр, описанный выше, действует следующим образом. Среди всех вариантов распознавания адреса сохраняются только те, которые принадлежат четырем регионам обязующего фильтра (см. элемент required): городу Москве, Красноярскому краю, Иркутской области и Тюменской области.

Затем из оставшихся вариантов удаляются адреса, принадлежащие регионам режекторного фильтра (см. элемент rejector). В данном случае такими регионами являются Тюменская и Иркутская области.

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

JSON-представление одного адресного объекта в рамках фильтра

Описание адресного объекта в рамках фильтра может быть выполнено двумя следующими способами.

  • Описание с помощью КЛАДР-кода объекта. В этом случае при описании объекта достаточно указать его код по справочнику КЛАДР. Например, для описания адресного объекта, соответствующего городу Екатеринбург, необходимо указать его КЛАДР-код "66000001".
  • Текстовое описание объекта. В этом случае объект описывается в виде строки, содержащей почтовый адрес объекта. Например, для описания адресного объекта, соответствующего городу Екатеринбург, необходимо указать его адрес следующим образом "обл Свердловская, г Екатеринбург". Текстовая форма записи адреса в общем случае может быть произвольной. Всякий раз, когда сервис получает в рамках фильтра описание адресного объекта в виде текста, выполняется его стандартизация и переход к КЛАДР-коду самого нижнего адресного поля, полученного в результате стандартизации адреса. Данный способ является менее предпочтительным, поскольку для получения КЛАДР-кода объекта сервис выполняет его распознавание, что приводит к замедлению обработки всего запроса в целом.

Примеры задания адресного объекта обоими способами приведены ниже.

Описание объекта с помощью КЛАДР-кода

{ 
  "code": "77" 
}

Текстовое описание объекта

{ 
  "address": "Москва", 
  "level": "Region" 
}

JSON-объект с описанием адресного объекта может содержать следующие дочерние элементы.

  • code – строка, задающая КЛАДР-код объекта. Если данный элемент присутствует в описании объекта, считается, что объект задается с помощью КЛАДР-кода. В этом случае остальные JSON-элементы в описании объекта игнорируются.
  • address – строка, задающая почтовый адрес объекта. Данный элемент предназначен для использования текстового описания объекта.
  • level – строка, содержащая имя уровня адресного объекта. Может принимать одно из значений, описанных по следующей ссылке cleanse/address#JSON-level. Данный элемент является необязательным, он позволяет подсказать сервису, какому уровню принадлежит адресный объект, текстовое описание которого приведено в элементе address. Использование данного элемента полезно, когда текстовое описание формируется на основании исходных данных сомнительного качества. Например, если исходные данные для обработки адресов берутся из некоторой таблицы базы данных, в которой адрес представлен в одной колонке, но также существует вторая колонка, содержащая название региона, которому принадлежит адрес. В этом случае информацию из второй колонки можно взять для генерации фильтра, используя при этом в качестве текстового описания имя региона. Для повышения достоверности такого фильтра можно указать в описании объекта "level": "Region". Это позволит сервису осуществить более точный переход от текстового описания к его КЛАДР-коду.

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

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

<ProcessChunkRequest>
  <filters>
    <priority>
      <item code="24" address="Красноярский край"/>
    </priority>
  </filters>

  <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-элементами.

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

XML-элемент filters: опциональный фильтр почтовых адресов

XML-элемент filters позволяет задать настройки адресного фильтра, применимого к каждому почтовому адресу, обрабатываемому в рамках пакета. Данный XML-элемент эквивалентен описанному выше JSON-объекту filters.

Ниже приведено XML-представление фильтра, пример которого был рассмотрен выше при описании запроса в формате JSON.

  <filters>
    
    <!-- список регионов приоритетного фильтра -->
    <priority>
      <item address="г Москва" level="Region"/>
    </priority>

    <!-- список регионов обязующего фильтра -->
    <required>
      <item code="77" address="г Москва"/>
      <item address="Красноярский край"/>
      <item address="обл Иркутская"/>
      <item address="Тюменская" level="Region"/>
    </required>

    <!-- список регионов режекторного фильтра -->
    <rejector>
      <item address="Тюменская область" level="Region"/>
      <item address="Иркутская" level="Region"/>
    </rejector>

  </filters>

Описание каждого из трех типов фильтров: приоритетного, обязующего и режекторного в рамках XML-элемента filters выполняется с помощью дочерних XML-элементов priority, required и rejector соответственно. Они в свою очередь содержат списки дочерних XML-элементов item, каждый из которых содержит описание одного из адресных объектов фильтра. Описание этих объектов приведено в следующем подразделе.

XML-представление одного адресного объекта в рамках фильтра

Адресные объекты, как и в случае с JSON-представлением, могут задаваться двумя способами – с помощью КЛАДР-кода и посредством текстового описания. Примеры задания адресного объекта обоими способами приведены ниже.

Описание объекта с помощью КЛАДР-кода

<item code="77" 
      address="г Москва"/>

Текстовое описание объекта

<item address="г Москва" 
      level="Region"/>

XML-элемент item с описанием адресного объекта может содержать следующие атрибуты.

  • code – задает КЛАДР-код объекта. Если данный атрибут присутствует в описании объекта, считается, что объект задается первым способом - с помощью КЛАДР-кода. В этом случае остальные атрибуты элемента item игнорируются. Данный атрибут эквивалентен JSON-элементу code, описанному выше в рамках JSON-представления фильтра.
  • address – задает почтовый адрес объекта при использовании текстового способа описания. Данный атрибут эквивалентен JSON-элементу address, описанному выше в рамках JSON-представления фильтра.
  • level – задает имя уровня адресного объекта. Атрибут не является обязательным, он позволяет подсказать сервису, какому уровню принадлежит адресный объект, текстовое описание которого приведено в атрибуте address. Данный атрибут эквивалентен JSON-элементу level, описанному выше в рамках JSON-представления фильтра.

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

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

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

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

https://ahunter.ru/site/cleanse/chunk?user=demotoken;output=json;input=json;query=%7B%0D%0A%20%20%22filters%22%3A%0D ... %7D%0D%0A%20%20%5D%0D%0A%7D

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

  • user=demotoken - сообщает сервису API-токен пользователя. При отправке реального запроса вместо значения demotoken нужно подставить токен из личного кабинета.
  • output=json - сообщает сервису о том, что необходимо вернуть ответ в формате JSON.
  • input=json - сообщает сервису, что исходный запрос передается в формате JSON.
  • query=%7B%0D%0A%20%20%22filters%22%3A%0D ... %7D%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.

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

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

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

https://ahunter.ru/site/cleanse/chunk?user=demotoken;output=json|pretty|ageo;input=xml;
addresslim=3;phonelim=1;personlim=1;query=%3CProcessChunkRequest%3E%0D%0A ... %0A%3C%2FProcessChunkRequest%3E

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

  • 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. По существу возвращаемые в 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.

версия сервиса:
© ixLab, 2007-2017, e-mail: info@ixlab.ru
обработано за 0 (мс)