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

Параметр устарел.

Всегда возвращается значение ELIGIBLE — показы возможны.

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

Нет

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

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

Type

AdGroupTypesEnum

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

Subtype

AdGroupSubtypeEnum

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

UnifiedAdGroup

UnifiedAdGroupGet

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

Параметр

Тип

Описание

Статус

Структура AdGroupGetItem

ServingStatus

ServingStatusEnum

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

Параметр устарел. Всегда возвращается значение ELIGIBLE — показы возможны.

MobileAppAdGroup

MobileAppAdGroupGet

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

Параметр устарел и больше не поддерживается.

DynamicTextAdGroup

DynamicTextAdGroupGet

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

Параметр устарел и больше не поддерживается.

DynamicTextFeedAdGroup

DynamicTextFeedAdGroupGet

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

Параметр устарел и больше не поддерживается.

SmartAdGroup

SmartAdGroupGet

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

Параметр устарел и больше не поддерживается.

TextAdGroupFeedParams

TextAdGroupFeedParamsGet

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

Параметр устарел и больше не поддерживается.

Структура 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