Получение данных: метод get
Получение только запрашиваемых данных
При вызове метода 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 |
|||
|
long |
Количество возвращаемых объектов (размер страницы). От 0 до 10 000. Если не указано, используется ограничение 10 000. |
Нет |
|
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.