Получение данных: метод get

  1. Получение только запрашиваемых данных
  2. Критерии отбора
  3. Постраничная выборка

Получение только запрашиваемых данных

При вызове метода get необходимо в массиве FieldNames явно перечислить те параметры, которые требуется получить.

Пример

Если в запросе указано

"FieldNames": ["Id","Name","Status"]

будут получены идентификаторы, имена и статусы объектов.

Если требуется получить параметр, значение которого не задано, метод get возвращает в этом параметре значение null, см. раздел Значение null (nil).

Критерии отбора

Для отбора объектов в методе get предназначена входная структура SelectionCriteria. Состав критериев различен для разных сервисов и приведен в описании метода get для каждого сервиса.

Каждый критерий работает как оператор IN в SQL. Если задано несколько критериев, они объединяются по условию AND: будут получены объекты, отвечающие одновременно всем критериям. Если не найдено ни одного объекта, соответствующего критериям, возвращается пустая структура.

Примечание. Метод get игнорирует идентификаторы несуществующих, удаленных и не принадлежащих рекламодателю объектов, никаких ошибок и предупреждений для них не выдает.

Пример

Если в запросе заданы критерии

"SelectionCriteria": {
   "CampaignIds": [1234567,1234589,1234777],
   "Statuses": ["PREACCEPTED","ACCEPTED"]
}

будут получены объекты со статусом PREACCEPTED или ACCEPTED, которые относятся к кампании 1234567, 1234589 или 1234777. Аналогично SQL-оператору SELECT ... WHERE CampaignId IN (1234567,1234589,1234777) AND Status IN ("PREACCEPTED","ACCEPTED").

Постраничная выборка

Метод get возвращает не более 10 000 объектов за один запрос. Постраничное получение данных можно организовать с помощью структуры

"Page": { /* LimitOffset */
   "Limit": (long),
   "Offset": (long)
}
Параметр Тип Описание Обяза-тельный
Структура LimitOffset
Limit long Количество возвращаемых объектов (размер страницы). От 0 до 10 000. Если не указано, используется ограничение 10 000. Нет
Offset long Количество объектов, которое должно быть пропущено при выборке. Если не указано, подразумевается 0. Нет
Параметр Тип Описание Обяза-тельный
Структура LimitOffset
Limit long Количество возвращаемых объектов (размер страницы). От 0 до 10 000. Если не указано, используется ограничение 10 000. Нет
Offset long Количество объектов, которое должно быть пропущено при выборке. Если не указано, подразумевается 0. Нет

Пример 1

Если задано:

"Page": { /* LimitOffset */
   "Limit": 200,
   "Offset": 600
}

будут возвращены объекты с 601-го по 800-й.

Как определить, все ли объекты получены?

Если возвращенная страница — не последняя (в выборке остались еще объекты), то метод get возвращает поле LimitedBy — порядковый номер последнего возвращенного объекта. Чтобы получить следующую страницу, полученное значение LimitedBy нужно указать в качестве Offset при следующем вызове метода get с тем же SelectionCriteria.

Пример 2

Если в примере 1 ответ метода get не содержит параметра LimitedBy, то эта страница — последняя в выборке.

Если ответ содержит параметр LimitedBy со значением 800, в следующем запросе необходимо указать 

"Page": { /* LimitOffset */
   "Limit": 200,
   "Offset": 800
}

Пример 3

Если в запросе не было структуры Page, а ответ содержит параметр LimitedBy со значением 10 000, значит, в выборке более 10 000 объектов и была возвращена только первая страница. Для получения следующей страницы в следующем запросе необходимо указать

"Page": { /* LimitOffset */
   "Offset": 10000
}

Параметр Limit указывать необязательно: по умолчанию используется ограничение 10 000.