get

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

Узнайте больше

Ограничения

Для работы с Единой перфоманс-группой используется адрес https://api.direct.yandex.com/v501/.

Метод возвращает не более 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" | "SMART_AD_GROUP" | "UNIFIED_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" | "AutotargetingCategories" ), ... ],
    "DynamicTextFeedAdGroupFieldNames": [( "Source" | "FeedId" | "SourceType" | "SourceProcessingStatus" | "AutotargetingCategories" ), ... ],
    "SmartAdGroupFieldNames": [( "FeedId" | "AdTitleSource" | "AdBodySource" ), ... ],
    "TextAdGroupFeedParamsFieldNames": [ ( "FeedId" | "FeedCategoryIds" ) ],
    "UnifiedAdGroupFieldNames" : [ ("OfferRetargeting") ],
    "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 не возвращаются.

Нет

SmartAdGroupFieldNames

array of SmartAdGroupFieldEnum

Имена параметров группы смарт-баннеров. См. Тип группы.

Примечание

Если согласно SelectionCriteria отобрана группа другого типа, параметры из SmartAdGroupFieldNames не возвращаются.

Нет

TextAdGroupFeedParamsFieldNames

array of TextAdGroupFeedParamsFieldEnum

Имена параметров группы текстово-графических объявлений, для которых источником данных является фид. См. Тип группы.

Примечание

Если согласно SelectionCriteria отобрана группа другого типа, параметры из TextAdGroupFeedParamsFieldNames не возвращаются.

Нет

UnifiedAdGroupFieldNames

array of UnifiedAdGroupFieldEnum

Имена параметров единой перфоманс группы. См. Тип группы.

Примечание

Если согласно SelectionCriteria отобрана группа другого типа, параметры из UnifiedAdGroupFieldNames не возвращаются.

Нет

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" | "SMART_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" ),
        "AutotargetingCategories" : { /* nillable */
          "Items" : [{ /* required */
            "Category" : ("EXACT"|"ALTERNATIVE"|"COMPETITOR"|"BROADER"|"ACCESSORY") /* required */,
            "Value" : ("YES"|"NO") /* required */
          }, ...]
        }, ...]
      }, ...],
      "DynamicTextFeedAdGroup": [{  /* DynamicTextFeedAdGroupGet */
        "Source": (string),
        "FeedId": (long),
        "SourceType": ( "RETAIL_FEED" | "UNKNOWN" ),
        "SourceProcessingStatus": ( "EMPTY_RESULT" | "PROCESSED" | "UNKNOWN" | "UNPROCESSED" ),
        "AutotargetingCategories" : { /* nillable */
          "Items" : [{ /* required */
            "Category" : ("EXACT"|"ALTERNATIVE"|"COMPETITOR"|"BROADER"|"ACCESSORY") /* required */,
            "Value" : ("YES"|"NO") /* required */
          }, ...]
        }, ...]
      }, ...],
      "SmartAdGroup": { /* SmartAdGroupGet */
        "FeedId": (long),
        "AdTitleSource": (string), /* nillable */
        "AdBodySource": (string) /* nillable */
      },
      "TextAdGroupFeedParams" : {  /* TextAdGroupFeedParamsGet */
        "FeedId" : (long) /* nillable */,
        "FeedCategoryIds" : { /* nillable */
          "Items" : [ (long) ] /* required */
        }
      },
      "UnifiedAdGroup" : {
        "OfferRetargeting" : ("YES"|"NO")
      }
    }, ... ],
  "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}

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

Status

StatusEnum

Статус группы. См. Статус группы.

ServingStatus

ServingStatusEnum

Статус возможности показов группы. См. Статус возможности показов группы.

Type

AdGroupTypesEnum

Тип группы объявлений. См. Тип группы.

Subtype

AdGroupSubtypeEnum

Подтип группы объявлений. Для групп с типом, отличным от DYNAMIC_TEXT_AD_GROUP и CPM_BANNER_AD_GROUP, возвращается значение NONE.

MobileAppAdGroup

MobileAppAdGroupGet

Параметры группы для рекламы мобильных приложений.

DynamicTextAdGroup

DynamicTextAdGroupGet

Параметры группы динамических объявлений, для которых источником данных является сайт.

DynamicTextFeedAdGroup

DynamicTextFeedAdGroupGet

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

SmartAdGroup

SmartAdGroupGet

Параметры группы смарт-баннеров.

TextAdGroupFeedParams

TextAdGroupFeedParamsGet

Параметры группы текстово-графических объявлений.

UnifiedAdGroup

UnifiedAdGroupGet

Параметры единой перфоманс группы. См. Тип группы.

Структура 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 — не удалось создать ни одного объявления.

AutotargetingCategories

array of AutotargetingCategoriesGetItem

Категории таргетинга, которые требуется добавить.

Структура AutotargetingCategories

Category

AutotargetingCategoriesEnum

Категория таргетинга:

  • EXACT — целевые запросы. Рекламное объявление точно отвечает на запросы пользователя;
  • ALTERNATIVE — альтернативные запросы. Пользователь ищет продукт, который можно заменить рекламируемым. При этом объявление также может удовлетворить запрос;
  • COMPETITOR — запросы с упоминанием конкурентов. Поиск рекламируемого продукта у конкурентов;
  • BROADER — широкие запросы. Запросы с интересом к продукту, примером которого является рекламное предложение;
  • ACCESSORY — сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с рекламируемым товаром или услугой.

Value

YesNoEnum

Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга.

Структура DynamicTextFeedAdGroupGet

Source

string

Идентификатор фида.

FeedId

long

Идентификатор фида.

SourceType

SourceTypeGetEnum

Тип источника данных. В настоящее время доступно только значение RETAIL_FEED.

SourceProcessingStatus

SourceProcessingStatusEnum

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

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

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

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

AutotargetingCategories

array of AutotargetingCategoriesGetItem

Категории таргетинга, которые требуется добавить.

Структура SmartAdGroupGet

FeedId

long

Идентификатор фида, на основе которого генерируются смарт-баннеры.

AdTitleSource

string, nillable

Название элемента фида, из которого нужно брать заголовок объявления. Если не задано, заголовок генерируется автоматически.

AdBodySource

string, nillable

Название элемента фида, из которого нужно брать текст объявления. Если не задано, текст генерируется автоматически.

Структура TextAdGroupFeedParamsGet

FeedId

long

Идентификатор фида, на основе которого требуется сгенерировать текстово-графические объявления.

FeedCategoryIds

ArrayOfLong

Идентификаторы категорий товаров, на основе которых требуется сгенерировать текстово-графические объявления.

Если идентификаторы категорий не заданы, используются все категории из фида.

Структура UnifiedAdGroupGet

OfferRetargeting

YesNoEnum

Признак включения офферного ретаргетинга.

Примеры

Пример запроса

{
  "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"
      }
    ]
  }
}
Предыдущая
delete
Следующая
update