get

Возвращает параметры групп, отвечающих заданным критериям.

  1. Ограничения
  2. Запрос
  3. Ответ
  4. Примеры

Ограничения

Метод возвращает не более 10 000 объектов.

Запрос

Структура запроса в формате JSON:

{
  "method": "get",
  "params": { /* params */
    "SelectionCriteria": {  /* AdGroupsSelectionCriteria */
      "CampaignIds": [(long), ... ],
      "Ids": [(long), ... ],
      "Types": [( "TEXT_AD_GROUP" | "MOBILE_APP_AD_GROUP" | "DYNAMIC_TEXT_AD_GROUP" | "CPM_BANNER_AD_GROUP" | "CPM_VIDEO_AD_GROUP" ), ... ],
      "Statuses": [( "ACCEPTED" | "DRAFT" | "MODERATION" | "PREACCEPTED" | "REJECTED" ), ... ],
      "ServingStatuses": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ],
      "AppIconStatuses": [( "ACCEPTED" | "MODERATION" | "REJECTED" ), ... ],
      "NegativeKeywordSharedSetIds": [(long), ... ]
    }, /* required */
    "FieldNames": [( "CampaignId" | ... | "Type" ), ... ], /* required */
    "MobileAppAdGroupFieldNames": [( "StoreUrl" | ... | "AppIconModeration" ), ... ],
    "DynamicTextAdGroupFieldNames": [( "DomainUrl" | "DomainUrlProcessingStatus" ), ... ],
    "DynamicTextFeedAdGroupFieldNames": [( "Source" | "SourceType" | "SourceProcessingStatus" ), ... ],
    "Page": {  /* LimitOffset */
      "Limit": (long),
      "Offset": (long)
    }
  }
}
Параметр Тип Описание Обязательный
Структура params (для JSON) / GetRequest (для SOAP)
SelectionCriteria AdGroupsSelectionCriteria Критерий отбора групп. Да
FieldNames array of AdGroupFieldEnum Имена параметров верхнего уровня, которые требуется получить. Да
MobileAppAdGroupFieldNames array of MobileAppAdGroupFieldEnum Имена параметров группы для рекламы мобильных приложений, которые требуется получить. См. Тип группы.
Примечание. Если согласно SelectionCriteria отобрана группа другого типа, параметры из MobileAppAdGroupFieldNames не возвращаются.
Нет
DynamicTextAdGroupFieldNames array of DynamicTextAdGroupFieldEnum Имена параметров группы динамических объявлений, для которых источником данных является сайт. См. Тип группы.
Примечание. Если согласно SelectionCriteria отобрана группа другого типа, параметры из DynamicTextAdGroupFieldNames не возвращаются.
Нет
DynamicTextFeedAdGroupFieldNames array of DynamicTextFeedAdGroupFieldEnum Имена параметров группы динамических объявлений, для которых источником данных является фид. См. Тип группы.
Примечание. Если согласно SelectionCriteria отобрана группа другого типа, параметры из DynamicTextFeedAdGroupFieldNames не возвращаются.
Нет
Page LimitOffset Структура, задающая страницу при постраничной выборке данных. Нет
Структура AdGroupsSelectionCriteria
CampaignIds array of long Отбирать группы указанных кампаний. От 1 до 10 элементов в массиве. Хотя бы один из параметров CampaignIds и Ids (могут присутствовать оба)
Ids array of long Отбирать группы с указанными идентификаторами. От 1 до 10 000 элементов в массиве.
Types array of AdGroupTypesEnum Отбирать группы с указанными типами. См. Тип группы. Нет
Statuses array of AdGroupStatusSelectionEnum Отбирать группы с указанными статусами. См. Статус группы. Нет
ServingStatuses array of ServingStatusEnum Отбирать группы с указанными статусами возможности показов. См. Статус возможности показов группы. Нет
AppIconStatuses array of AdGroupAppIconStatusSelectionEnum Отбирать группы по результату модерации иконки приложения:
  • ACCEPTED — принята модерацией;

  • MODERATION — находится на модерации;

  • REJECTED — отклонена.

Если параметр задан, будут получены только группы для рекламы мобильных приложений. Не следует задавать его, если требуется получить группы других типов.

Нет
NegativeKeywordSharedSetIds array of long Отбирать группы объявлений, в которых используется хотя бы один из указанных наборов минус-фраз. Нет

Ответ

Структура ответа в формате JSON:

{
  "result": { /* result */
    "AdGroups": [{  /* AdGroupGetItem */
      "Id": (long),
      "Name": (string),
      "CampaignId": (long),
      "RegionIds": [(long), ... ],
      "RestrictedRegionIds": {  /* ArrayOfLong */
        "Items": [(long), ... ] /* required */
      }, /* nillable */
      "NegativeKeywords": {  /* ArrayOfString */
        "Items": [(string), ... ] /* required */
      }, /* nillable */
      "NegativeKeywordSharedSetIds": { /* ArrayOfLong */
        "Items": [(long), ... ] /* required */
      }, /* nillable */
      "TrackingParams": (string),
      "Status": ( "ACCEPTED" | "DRAFT" | "MODERATION" | "PREACCEPTED" | "REJECTED" ),
      "ServingStatus": ( "ELIGIBLE" | "RARELY_SERVED" ),
      "Type": ( "TEXT_AD_GROUP" | "MOBILE_APP_AD_GROUP" | "DYNAMIC_TEXT_AD_GROUP" | "CPM_BANNER_AD_GROUP" | "CPM_VIDEO_AD_GROUP" ),
      "Subtype": ( "WEBPAGE" | "FEED" | "NONE" | "KEYWORDS" | "USER_PROFILE" ),
      "MobileAppAdGroup": {  /* MobileAppAdGroupGet */
        "StoreUrl": (string),
        "TargetDeviceType": [( "DEVICE_TYPE_MOBILE" | "DEVICE_TYPE_TABLET" ), ... ],
        "TargetCarrier": ( "WI_FI_ONLY" | "WI_FI_AND_CELLULAR" ),
        "TargetOperatingSystemVersion": (string),
        "AppIconModeration": {  /* ExtensionModeration */
          "Status": ( "ACCEPTED" | "MODERATION" | "REJECTED" ), /* required */
          "StatusClarification": (string)
        } /* nillable */
        "AppOperatingSystemType": ("IOS" | "ANDROID" | "OS_TYPE_UNKNOWN"),
        "AppAvailabilityStatus": ("UNPROCESSED" | "AVAILABLE" | "NOT_AVAILABLE")
      },
      "DynamicTextAdGroup": {  /* DynamicTextAdGroupGet */
        "DomainUrl": (string),
        "DomainUrlProcessingStatus": ("EMPTY_RESULT" | "PROCESSED" | "UNKNOWN" | "UNPROCESSED" )
      },
      "DynamicTextFeedAdGroup": {  /* DynamicTextFeedAdGroupGet */
        "Source": (string),
        "SourceType": ( "RETAIL_FEED" | "UNKNOWN" ),
        "SourceProcessingStatus": ( "EMPTY_RESULT" | "PROCESSED" | "UNKNOWN" | "UNPROCESSED" )
      }
    }, ... ],
  "LimitedBy": (long)
  }
}
Параметр Тип Описание
Структура result (для JSON) / GetResponse (для SOAP)
AdGroups array of AdGroupGetItem Группы объявлений.
LimitedBy long Порядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка.
Структура AdGroupGetItem
Id long Идентификатор группы объявлений.
Name string Название группы.
CampaignId long Идентификатор кампании.
RegionIds array of long

Идентификаторы регионов, для которых показы включены или выключены.

Идентификатор 0 — показывать во всех регионах.

Минус перед идентификатором региона — выключить показы в данном регионе. Например [1,-219] — показывать для Москвы и Московской области, кроме Черноголовки.

RestrictedRegionIds ArrayOfLong, nillable Идентификаторы регионов, в которых объявления не будут показаны в связи с законодательными ограничениями.
NegativeKeywords ArrayOfString, nillable

Минус-фразы, общие для всех ключевых фраз группы объявлений.

NegativeKeywordSharedSetIds ArrayOfLong, nillable Идентификаторы наборов минус-фраз. Не более 3 элементов в массиве.
TrackingParams string

GET-параметры для отслеживания источников переходов на сайт, которые добавляются в ссылку всех объявлений группы (не более 1024 символов). Могут содержать подстановочные переменные.

Например: from=direct&ad={ad_id}

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

Status StatusEnum Статус группы. См. Статус группы.
ServingStatus ServingStatusEnum Статус возможности показов группы. См. Статус возможности показов группы.
Type AdGroupTypesEnum Тип группы объявлений. См. Тип группы.
Subtype AdGroupSubtypeEnum Подтип группы объявлений. Для групп с типом, отличным от DYNAMIC_TEXT_AD_GROUP и CPM_BANNER_AD_GROUP, возвращается значение NONE.
MobileAppAdGroup MobileAppAdGroupGet Параметры группы для рекламы мобильных приложений. См. Тип группы.
DynamicTextAdGroup DynamicTextAdGroupGet Параметры группы динамических объявлений, для которых источником данных является сайт. См. Тип группы.
DynamicTextFeedAdGroup DynamicTextFeedAdGroupGet Параметры группы динамических объявлений, для которых источником данных является фид. См. Тип группы.
Структура MobileAppAdGroupGet
StoreUrl string

Ссылка на приложение в магазине приложений AppStore или Google Play (не более 1024 символов). Должна содержать протокол. Недоступна для изменения.

См. раздел Ссылка на приложение в магазине приложений помощи Директа.

Ограничение. Во всех группах объявлений одной кампании должна быть указана одинаковая ссылка на приложение.

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

TargetDeviceType array of DeviceTypeEnum На каких устройствах показывать объявления:
  • DEVICE_TYPE_MOBILE — смартфоны;

  • DEVICE_TYPE_TABLET — планшеты.

TargetCarrier CarrierEnum По каким типам подключения к интернету показывать объявления:
  • WI_FI_ONLY — только по Wi-FI;
  • WI_FI_AND_CELLULAR — по мобильной связи и Wi-Fi.
TargetOperatingSystemVersion string Минимальная версия операционной системы, на которой может быть показано объявление. Например, 2.3.
Примечание. Если минимальная версия ОС в магазине приложений выше, чем заданная в параметре, то объявления будут показаны только для версий ОС как в магазине приложений или выше.
AppIconModeration ExtensionModeration Результат модерации иконки мобильного приложения.
AppOperatingSystemType MobileOperatingSystemTypeEnum

Тип операционной системы (определяется автоматически на основании данных из магазина приложений):

  • IOS — iOS;
  • ANDROID — Android;
  • OS_TYPE_UNKNOWN — данные из магазина приложений еще не получены.
AppAvailabilityStatus AppAvailabilityStatusEnum

Доступно ли приложение в магазине приложений:

  • AVAILABLE — доступно;

  • NOT_AVAILABLE — недоступно;

  • UNPROCESSED — данные из магазина приложений еще не получены.

Структура ExtensionModeration
Status ModerationStatusEnum Результат модерации иконки мобильного приложения:
  • ACCEPTED — принята модерацией;

  • MODERATION — находится на модерации;

  • REJECTED — отклонена.

StatusClarification string Текстовое пояснение к статусу и/или причины отклонения на модерации.
Структура DynamicTextAdGroupGet
DomainUrl string Доменное имя сайта, для которого требуется сгенерировать динамические объявления (не более 100 символов). Протокол указывать не нужно.
DomainUrlProcessingStatus SourceProcessingStatusEnum

Статус генерации динамических объявлений:

  • UNPROCESSED — генерация объявлений не завершена;

  • PROCESSED — объявления созданы;

  • EMPTY_RESULT — не удалось создать ни одного объявления.

Структура DynamicTextFeedAdGroupGet
Source string Идентификатор фида.
SourceType SourceTypeGetEnum Тип источника данных. В настоящее время доступно только значение RETAIL_FEED.
SourceProcessingStatus SourceProcessingStatusEnum

Статус генерации динамических объявлений:

  • UNPROCESSED — генерация объявлений не завершена;

  • PROCESSED — объявления созданы;

  • EMPTY_RESULT — не удалось создать ни одного объявления.

Примеры

Пример запроса
{
  "method" : "get",
  "params" : {
    "SelectionCriteria" : {
      "CampaignIds" : [
        2991372,
        4193065,
        4193084,
        7273721
      ],
      "Statuses" : [ "DRAFT" ]
    },
    "FieldNames" : [
      "Id",
      "Name",
      "CampaignId",
      "Status",
      "RegionIds",
      "NegativeKeywords"
    ]
  }
}
Пример ответа
{
  "result" : {
    "AdGroups" : [
      {
        "Id" : 45625656,
        "Status" : "DRAFT",
        "CampaignId" : 4193065,
        "RegionIds" : [
          225
        ],
        "NegativeKeywords" : null,
        "Name" : "AdGroup #1"
      },
      {
        "Id" : 198171138,
        "Status" : "DRAFT",
        "CampaignId" : 7273721,
        "RegionIds" : [
          225
        ],
        "NegativeKeywords" : null,
        "Name" : "AdGroup #2"
      },
      {
        "Id" : 636056252,
        "Status" : "DRAFT",
        "CampaignId" : 7273721,
        "RegionIds" : [
          0
        ],
        "NegativeKeywords" : {
          "Items" : [
            "куплю"
          ]
        },
        "Name" : "AdGroup #3"
      }
    ]
  }
}