--- metadata: - name: generator content: Diplodoc Platform v5.52.0 alternate: - https://yandex.com/dev/direct/doc/en/keywords/add.md - https://yandex.com/dev/direct/doc/ru/keywords/add.md - href: ru/keywords/add.md type: text/markdown title: Markdown version - href: ../llms.txt type: text/markdown title: llms.txt sourcePath: ru/ref-v5/keywords/add.md --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/direct/doc/ru/llms.txt # add Создает ключевые фразы и автотаргетинги. {% note alert %} Метод не сохраняет дубликаты фраз, см. [Дубликаты фраз](https://yandex.ru/dev/direct/doc/dg/objects/keyword.html). {% endnote %} Ставку можно назначить в зависимости от того, какая стратегия выбрана в кампании: - Если в кампании настроена ручная стратегия, то можно указать параметр `Bid`, а если стратегия предусматривает независимое управление ставками в сетях — параметры `Bid` и `ContextBid`. В случае если элемент входного массива содержит параметры, не соответствующие стратегии, то значения этих параметров будут сохранены и будет выдано предупреждение. - Если в кампании настроена автоматическая стратегия, а при создании фразы заданы параметры `Bid` и/или `ContextBid`, то эти значения ставок **не будут применены**: в момент смены стратегии с автоматической на ручную будут заданы ставки, подобранные автоматическим алгоритмом. - Если в кампании настроена ручная стратегия без независимого управления ставками в сетях, а при создании фразы задан параметр `ContextBid`, то в дальнейшем в момент смены стратегии на ручную с независимым управлением ставками заданное значение ставки будет применено. Если стратегия предполагает назначение ставки, а ставка не указана, по умолчанию назначается: - для ключевой фразы — минимальная ставка; - для автотаргетинга для ставки `ContextBid` – ставка, рассчитанная на основе ставок по ключевым фразам в группе объявлений (в случае отсутствия фраз в группе — минимальная ставка). - для автотаргетинга для ставки `Bid` – автоматическая ставка. Если автоматическая ставка выключена – ставка, рассчитанная на основе ставок по ключевым фразам в группе объявлений (ручная ставка рассчитывается всегда, но используется только при выключенной автоставке). В случае отсутствия фраз в группе используется минимальная ставка. По умолчанию все категории таргетинга включены. Категории, для которых явно не указано значение "YES" или "NO", считаются включенными. ## Узнайте больше - [Как работает метод add](https://yandex.ru/dev/direct/doc/dg/best-practice/modify.html) - [Как обрабатывать ошибки](https://yandex.ru/dev/direct/doc/dg/concepts/errors.html) - [Автотаргетинг](https://yandex.ru/dev/direct/doc/dg/best-practice/auto-targeting.html) ## Ограничения {#restrictions} Не более 1000 объектов в одном вызове метода. Не более 1 автотаргетинга в группе объявлений. Не допускается добавление ключевых фраз в группу объявлений с типом CPM_BANNER_AD_GROUP и подтипом USER_PROFILE, а также в группу объявлений с типом DYNAMIC_TEXT_AD_GROUP. Не допускается добавление автотаргетингов в группы объявлений с типом DYNAMIC_TEXT_AD_GROUP и CPM_BANNER_AD_GROUP. Ограничение на количество ключевых фраз в группе объявлений для пользователя можно получить с помощью метода [Clients](https://yandex.ru/dev/direct/doc/ref-v5/clients/clients.html).[get](https://yandex.com/dev/direct/doc/ru/clients/get.md) или [AgencyClients](https://yandex.ru/dev/direct/doc/ref-v5/agencyclients/agencyclients.html).[get](https://yandex.ru/dev/direct/doc/ref-v5/agencyclients/get.html) (элемент KEYWORDS_TOTAL_PER_ADGROUP массива Restrictions). Ограничения на количество слов и символов в ключевой фразе см. в разделе [Количественные ограничения](https://yandex.ru/support/direct/troubleshooting/interface.html#limitations) Справки Директа. ## Запрос {#input} Структура запроса в формате JSON: ```javascript translate=no { "method": "add", "params": { /* params */ "Keywords": [{ /* KeywordAddItem */ "Keyword": (string), /* required */ "AdGroupId": (long), /* required */ "Bid": (long), "AutotargetingSearchBidIsAuto" : ("YES" | "NO"), "ContextBid": (long), "StrategyPriority": ( "LOW" | "NORMAL" | "HIGH" ), "UserParam1": (string), "UserParam2": (string), "AutotargetingCategories" : [{ /* AutotargetingCategoriesAddItem */ "Category" : ("EXACT"|"ALTERNATIVE"|"COMPETITOR"|"BROADER"|"ACCESSORY") /* required */, "Value" : ("YES"|"NO") /* required */ }, ...], "AutotargetingSettings" : { "Categories" : { "Exact" : ("YES"|"NO"), "Narrow" : ("YES"|"NO"), "Alternative" : ("YES"|"NO"), "Accessory" : ("YES"|"NO"), "Broader" : ("YES"|"NO") }, "BrandOptions" : { "WithoutBrands" : ("YES"|"NO"), "WithAdvertiserBrand" : ("YES"|"NO"), "WithCompetitorsBrand" : ("YES"|"NO") } } }, ... ] /* required */ } } ``` #| || **Параметр** | **Тип** | **Описание** | **Обязательный** || || **Структура params (для JSON) / AddRequest (для SOAP)** || || `Keywords` | array of KeywordAddItem | Ключевые фразы и автотаргетинги, которые требуется добавить. | Да || || **Структура KeywordAddItem** || || `AdGroupId` | long | Идентификатор группы, в которую добавляется ключевая фраза или автотаргетинг. | Да || || `Keyword` | string | Ключевая фраза. Может содержать минус-слова, которые указывают со знаком минус перед словом, например _молния -гром -дождь_. Длина ключевой фразы — не более 4096 символов. Оператор `!` перед минус-словом не учитывается в длине фразы (последовательность `-!` считается как один символ). Не более 7 слов в ключевой фразе, без учета стоп-слов и минус-слов. Каждое слово — не более 35 символов, без учета минуса перед минус-словом. {% note info %} Минус-слова, общие для всех ключевых фраз в группе объявлений, предпочтительно задавать в параметре группы [NegativeKeywords](*NegativeKeywords). {% endnote %} Если указано значение `---autotargeting`, будет создан автотаргетинг и появится возможность указать автоматическую ставку (`AutotargetingSearchBidIsAuto`). | Да || || `Bid` | long | Ставка на поиске, умноженная на 1 000 000. Целое число. Только для ручной стратегии. Указывается в валюте пользователя. Ограничения представлены в справочнике валют, который можно получить с помощью метода [Dictionaries](https://yandex.com/dev/direct/doc/ru/dictionaries/dictionaries.md).[get](https://yandex.com/dev/direct/doc/ru/dictionaries/get.md), указав в запросе имя справочника `Currencies`. | Нет || || `AutotargetingSearchBidIsAuto` | YesNoEnum | Признак включения опции [автоматической ставки](https://yandex.ru/support/direct/impression-criteria/autotargeting.html#autotargeting__auto-bids). Можно одновременно указать ручную ставку (`Bid`) и включить автоставку (`AutotargetingSearchBidIsAuto`). В этом случае будет работать автоставка, а ручная будет использоваться в случае отключения автоматической. Если указана ручная ставка `Bid`: значение автоматической ставки (`AutotargetingSearchBidIsAuto`) будет выставлено NO, если в явном виде не прислано иное значение автоставки. Если не указана ручная ставка `Bid`: значение автоматической ставки (`AutotargetingSearchBidIsAuto`) будет выставлено YES, если в явном виде не прислано иное значение автоставки. | Нет || || `ContextBid` | long | Ставка в сетях, умноженная на 1 000 000. Целое число. Только для ручной стратегии с независимым управлением ставками в Рекламной сети. Указывается в валюте пользователя. Ограничения представлены в справочнике валют, который можно получить с помощью метода [Dictionaries](https://yandex.com/dev/direct/doc/ru/dictionaries/dictionaries.md).[get](https://yandex.com/dev/direct/doc/ru/dictionaries/get.md), указав в запросе имя справочника `Currencies`. {% note alert %} Показ графического объявления возможен только при условии, что ставка не ниже минимальной ставки для объявления с включенным в него изображением. {% endnote %} | Нет || || `StrategyPriority` | PriorityEnum | Приоритет ключевой фразы или автотаргетинга: LOW, NORMAL или HIGH. Только для автоматической стратегии. {% note alert %} Параметр не используется, переданное значение игнорируется. {% endnote %} | Нет || || `UserParam1` | string | Значение [подстановочной переменной](https://yandex.ru/dev/direct/doc/dg/objects/keyword.html)`{param1}`. Не более 255 символов. | Нет || || `UserParam2` | string | Значение [подстановочной переменной](https://yandex.ru/dev/direct/doc/dg/objects/keyword.html)`{param2}`. Не более 255 символов. | Нет || || `AutotargetingCategories` | array of [AutotargetingCategoriesAddItem](#AutotargetingCategoriesAddItem) | Категории таргетинга, которые требуется добавить. {% note alert %} Структура устарела и скоро перестанет поддерживаться. Нельзя одновременно передать `AutotargetingCategories` и `AutotargetingSettings`, вернется ошибка валидации. {% endnote %} | Нет || || `AutotargetingSettings` | [AutotargetingSettingsAddItem](#AutotargetingSettingsAddItem) | Настройки таргетинга, которые требуется добавить. | Нет || || **Структура AutotargetingCategoriesAddItem** || || `Category` | AutotargetingCategoriesEnum | Категория таргетинга: - EXACT — целевые запросы. Объявление точно отвечает на запросы пользователя; - ALTERNATIVE — альтернативные запросы. Пользователь ищет продукт, который можно заменить продвигаемым. При этом объявление также может удовлетворить запрос; - COMPETITOR — запросы с упоминанием конкурентов. Поиск продвигаемого продукта у конкурентов; - BROADER — широкие запросы. Запросы с интересом к продукту, примером которого является предложение; - ACCESSORY — сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с продвигаемым товаром или услугой. {% note alert %} Поле устарело и скоро перестанет поддерживаться. Настройки, заданные с помощью API, сконвертируются в веб-интерфейсе по следующим правилам: {% endnote %} #| || **API** | **Веб-интерфейс** || || Включенная категория `EXACT`. | Включенные категории «Целевые», «Узкие». || || Включенная категория `COMPETITOR` (если это единственная включенная категория). | Включенная опция упоминания брендов «Конкуренты» + отключение остальных опций упоминания брендов + включение всех категорий. || || Включенная категория `COMPETITOR` (если это не единственная включенная категория). | Включенная опция упоминания брендов «Конкуренты». || || Выключенная категория `COMPETITOR`. | Выключенная опция упоминания брендов «Конкуренты». || |# | Да || || `Value` | YesNoEnum | Признак включения указанной категории таргетинга. По умолчанию включены все категории таргетинга. | Да || || **Структура AutotargetingSettingsAddItem** || || `Categories` | AutotargetingSettingsCategoriesFieldNames | Категории таргетинга. Доступные опции: - Exact – целевые запросы. Объявление точно отвечает на запросы пользователя. - Narrow – узкие запросы. Объявление шире, чем запросы пользователя. - Alternative – альтернативные запросы. Пользователь ищет продукт, который можно заменить продвигаемым. При этом объявление также может удовлетворить запрос. - Accessory – сопутствующие запросы. Запросы по продуктам, которые могут быть интересны вместе с продвигаемым товаром или услугой. - Broader – широкие запросы. Запросы с интересом к продукту, примером которого является предложение. | Нет || || `BrandOptions` | AutotargetingSettingsBrandOptionsFieldNames | Настройки брендовости. Доступные опции: - WithoutBrands – без упоминания брендов. - WithAdvertiserBrand – с упоминанием бренда пользователя. - WithCompetitorsBrand – с упоминанием брендов конкурентов. | Нет || |# ## Ответ {#output} Структура ответа в формате JSON: ```javascript translate=no { "result": { /* result */ "AddResults": [{ /* ActionResult */ "Id": (long), "Warnings": [{ /* ExceptionNotification */ "Code": (int), /* required */ "Message": (string), /* required */ "Details": (string) }, ... ], "Errors": [{ /* ExceptionNotification */ "Code": (int), /* required */ "Message": (string), /* required */ "Details": (string) }, ... ] }, ... ] /* required */ } } ``` #| || **Параметр** | **Тип** | **Описание** || || **Структура result (для JSON) / AddResponse (для SOAP)** || || `AddResults` | array of ActionResult | Результаты добавления ключевых фраз и автотаргетингов. || || **Структура ActionResult** || || `Id` | long | Идентификатор созданной ключевой фразы или автотаргетинга. Возвращается в случае отсутствия ошибок, см. раздел [Операции над массивом объектов](https://yandex.ru/dev/direct/doc/dg/best-practice/modify.html). || || `Warnings` | array of [ExceptionNotification](https://yandex.ru/dev/direct/doc/dg/best-practice/modify.html) | Предупреждения, возникшие при выполнении операции. || || `Errors` | array of [ExceptionNotification](https://yandex.ru/dev/direct/doc/dg/best-practice/modify.html) | Ошибки, возникшие при выполнении операции. || |#