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" ), ... ],
      "Statuses": [( "ACCEPTED" | "DRAFT" | "MODERATION" | "PREACCEPTED" | "REJECTED" ), ... ],
      "ServingStatuses": [( "ELIGIBLE" | "RARELY_SERVED" ), ... ],
      "AppIconStatuses": [( "ACCEPTED" | "MODERATION" | "REJECTED" ), ... ]
    }, /* 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)
SelectionCriteriaAdGroupsSelectionCriteriaКритерий отбора групп.Да
FieldNamesarray of AdGroupFieldEnumИмена параметров верхнего уровня, которые требуется получить.Да
MobileAppAdGroupFieldNamesarray of MobileAppAdGroupFieldEnumИмена параметров группы для рекламы мобильных приложений, которые требуется получить. См. Тип группы.
Примечание. Если согласно SelectionCriteria отобрана группа другого типа, параметры из MobileAppAdGroupFieldNames не возвращаются.
Нет
DynamicTextAdGroupFieldNamesarray of DynamicTextAdGroupFieldEnumИмена параметров группы динамических объявлений, для которых источником данных является сайт. См. Тип группы.
Примечание. Если согласно SelectionCriteria отобрана группа другого типа, параметры из DynamicTextAdGroupFieldNames не возвращаются.
Нет
DynamicTextFeedAdGroupFieldNamesarray of DynamicTextFeedAdGroupFieldEnumИмена параметров группы динамических объявлений, для которых источником данных является фид. См. Тип группы.
Примечание. Если согласно SelectionCriteria отобрана группа другого типа, параметры из DynamicTextFeedAdGroupFieldNames не возвращаются.
Нет
PageLimitOffsetСтруктура, задающая страницу при постраничной выборке данных.Нет
Структура AdGroupsSelectionCriteria
CampaignIdsarray of longОтбирать группы указанных кампаний. От 1 до 10 элементов в массиве.Хотя бы один из параметров CampaignIds и Ids (могут присутствовать оба)
Idsarray of longОтбирать группы с указанными идентификаторами. От 1 до 10 000 элементов в массиве.
Typesarray of AdGroupTypesEnumОтбирать группы с указанными типами. См. Тип группы.Нет
Statusesarray of AdGroupStatusSelectionEnumОтбирать группы с указанными статусами. См. Статус группы.Нет
ServingStatusesarray of ServingStatusEnumОтбирать группы с указанными статусами возможности показов. См. Статус возможности показов группы.Нет
AppIconStatusesarray of AdGroupAppIconStatusSelectionEnumОтбирать группы по результату модерации иконки приложения:
  • ACCEPTED — принята модерацией;

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

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

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

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

Ответ

Структура ответа в формате 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 */
      "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" ),
      "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)
AdGroupsarray of AdGroupGetItemГруппы объявлений.
LimitedBylongПорядковый номер последнего возвращенного объекта. Передается в случае, если количество объектов в ответе было ограничено лимитом. См. раздел Постраничная выборка.
Структура AdGroupGetItem
IdlongИдентификатор группы объявлений.
NamestringНазвание группы.
CampaignIdlongИдентификатор кампании.
RegionIdsarray of long

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

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

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

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

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

TrackingParamsstring

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

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

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

StatusStatusEnumСтатус группы. См. Статус группы.
ServingStatusServingStatusEnumСтатус возможности показов группы. См. Статус возможности показов группы.
TypeAdGroupTypesEnumТип группы объявлений. См. Тип группы.
SubtypeAdGroupSubtypeEnumПодтип группы объявлений. Для групп с типом, отличным от DYNAMIC_TEXT_AD_GROUP и CPM_BANNER_AD_GROUP, возвращается значение NONE.
MobileAppAdGroupMobileAppAdGroupGetПараметры группы для рекламы мобильных приложений. См. Тип группы.
DynamicTextAdGroupDynamicTextAdGroupGetПараметры группы динамических объявлений, для которых источником данных является сайт. См. Тип группы.
DynamicTextFeedAdGroupDynamicTextFeedAdGroupGetПараметры группы динамических объявлений, для которых источником данных является фид. См. Тип группы.
Структура MobileAppAdGroupGet
StoreUrlstring

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Структура DynamicTextFeedAdGroupGet
SourcestringИдентификатор фида.
SourceTypeSourceTypeGetEnumТип источника данных. В настоящее время доступно только значение RETAIL_FEED.
SourceProcessingStatusSourceProcessingStatusEnum

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

  • 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"
      }
    ]
  }
}