Справочник запросов. Партнерский API Яндекс Маркета для модели ADV. Руководство разработчика
Внимание. Маркет постепенно перестает поддерживать XML. Поэтому мы рекомендуем переходить на JSON. Сейчас XML можно использовать, если добавить в запрос Content-Type: application/xml. Без этого будут ошибки.
| Базовые запросы |
|---|
|
| Настройки размещения |
|
| Отзывы |
|
| Ассортимент |
|
| Управление показом предложений |
|
| Управление ценами |
|
Отчеты |
|
| Модели товаров |
|
| Финансы |
|
| Статистика |
|
| Геобаза |
|
| Точки продаж |
|
| Контроль качества |
|
Была ли статья полезна?
О справочнике
Ограничение.
Параметр StrategyPriority скоро перестанет приниматься и возвращаться в сервисах: AudienceTargets, Bids, DynamicTextAdTargets, KeywordBids, Keywords и SmartAdTargets. Пожалуйста, обновите свои приложения до конца января 2021.
Справочник содержит описание сервисов API Яндекс Директа версии 5. Документ адресован разработчикам приложений по управлению контекстной рекламой в Директе.
Ниже перечислены сервисы и методы API:
| Кампании | Группы объявлений | Объявления | Ключевые фразы и автотаргетинги |
|---|---|---|---|
Сервис: Campaigns Методы:
| Сервис: AdGroups Методы:
| Сервис: Ads Методы:
| Сервис: Keywords Методы:
|
| Ставки | Корректировки ставок | Наборы минус-фраз | Предобработка ключевых фраз |
Сервис: Bids Методы:
Сервис: KeywordBids Методы:
| Сервис: BidModifiers Методы:
| Сервис: NegativeKeywordSharedSets Методы:
| Сервис: KeywordsResearch Методы:
|
| Организации | Визитки | Изображения | Креативы |
Сервис: Businesses Метод: get | Сервис: VCards Методы:
| Сервис: AdImages Методы:
| Сервис: Creatives Методы:
|
| Видео | Турбо-страницы | Данные из форм на Турбо-страницах | Быстрые ссылки |
Сервис: AdVideos Методы:
| Сервис: TurboPages Метод: get | Сервис: Leads Метод: get | Сервис: Sitelinks Методы:
|
| Расширения | Условия нацеливания для динамических объявлений по фидам | Условия нацеливания на аудиторию | Условия подбора аудитории |
Сервис: AdExtensions Методы:
| Сервис: DynamicFeedAdTargets Методы:
| Сервис: AudienceTargets Методы:
| Сервис: RetargetingLists Методы:
|
| Условия нацеливания для смарт-баннеров | Условия нацеливания для динамических объявлений | Клиенты | Фиды |
Сервис: SmartAdTargets Методы:
| Сервис: DynamicTextAdTargets Методы:
| Сервис: Clients Методы:
Сервис: AgencyClients Методы:
| Сервис: Feeds Методы:
|
| Справочники | Изменения | ||
Сервис: Dictionaries Метод: get | Сервис: Changes Методы:
|
Примечание.
Методы для управления общими счетами, прогноза бюджета и подбора фраз, выполнения финансовых операций доступны в API версии 4 (Live 4). См. раздел Методы документации API версии 4 (Live 4).
Была ли статья полезна?
Предыдущая
Список терминов
Следующая
AdExtensions: операции с расширениями объявлений
Структура запроса. Описание API
Внимание. Яндекс Коннект больше не поддерживается. API каталога будет закрыт с 01 марта 2023 г.
Для управления организациями, пользователями и доменами перейдите в Яндекс 360 для бизнеса.
Документация по API 360 (рус.)
Формат запроса Common Directory API:
POST— Создать объект."}}">|GET— Получить информацию об объекте или списке объектов."}}">|
PATCH— Изменение параметров существующего объекта. Запросы, отправленные сМетод PATCHизменяет только параметры, явно указанные в теле запроса."}}">|DELETE— Удалить объект."}}"> /\nВерсия API каталога. Текущая версия API —
\n "}}">/\nv6.Тип ресурса, к которому обращается API:
\n \n "}}">/\nИдентификатор ресурса.
\n "}}">/?\nНекоторые запросы содержат дополнительные параметры. Эти параметры описаны в разделах, посвященных запросам API.
\n "}}">=<значение1>&<параметр2>=<значение2> HTTP/1.1
\n
Хост— Содержит адрес хоста, предоставляющего API. Значение всегда должно бытьhttps://api.directory.yandex.net.\n
"}}">: https://api.directory.yandex.net\n
Авторизация— содержит токен OAuth в полеOAuth <token value> формат, например:\n
Авторизация: OAuth 0c4181a7c2cf4521964a72ff57a34a07\n
"}}">: OAuth\n
Content-Type(только для запросов с методамиPOSTиPATCH) — Формат данных запроса.Значение всегда должно быть
application/json; кодировка=utf-8.\n
"}}">: приложение/json; кодировка = utf-8\n
Принять(только для запросов с методомGET) — ожидаемый формат данных ответа. Значение всегда должно бытьapplication/json.\n
"}}">: приложение/json\n
X-Org-ID— Код компании.Заголовок необходимо передавать только в том случае, если запрос инициирован администратором нескольких компаний.
\n
"}}">: <идентификатор компании> ... {json-объект | json-array}
Запросы к Directory API принимают один из следующих HTTP-методов:
GET— Получить информацию об объекте или списке объектов.POST— Создать объект.ПАТЧ— Изменение параметров существующего объекта. Запросы, отправленные методомPATCH, изменяют только параметры, явно указанные в теле запроса.УДАЛИТЬ— Удалить объект.
-
Версия API каталога.
Текущая версия API — v6.-
Тип ресурса, к которому обращается API:
-
Идентификатор ресурса.
Некоторые запросы содержат дополнительные параметры. Эти параметры описаны в разделах, посвященных запросам API.
Каждый запрос, отправляемый в Directory API, должен содержать HTTP-заголовок:
Хост— Содержит адрес хоста, предоставляющего API. Значение всегда должно бытьhttps://api.directory.yandex.net.Authorization— Contains an OAuth token in theOAuthformat, for example:Authorization: OAuth 0c4181a7c2cf4521964a72ff57a34a07
Accept(only for requests with theGETmethod) — Ожидаемый формат данных ответа.
Значение всегда должно быть приложение/json.Content-Type(только для запросов с методамиPOSTиPATCH) — формат данных запроса. Значение всегда должно бытьapplication/json; кодировка=utf-8.X-Org-ID— Код компании. Заголовок необходимо передавать только в том случае, если запрос инициирован администратором нескольких компаний.
Некоторые запросы могут иметь дополнительные заголовки. Эти заголовки описаны в разделах, посвященных запросам API.
Тело запроса содержит информацию, необходимую для создания или изменения объекта. Информация должна передаваться в формате JSON.
Описание возможных полей и структуры тела можно найти в разделах, посвященных запросам API.
В ответ на некоторые запросы API создает список объектов (например, список пользователей или отделов). Для экономии ресурсов эти списки разбиты на страницы. Ответы на запросы содержат только одну страницу. Вы можете установить количество объектов на странице и их количество с помощью per_page и page параметров соответственно.
Если параметры per_page и page опущены, список разбивается на страницы по 20 элементов на странице. Ответ содержит первую страницу списка.
Запросить список сотрудников:
GET /v6/users/?page=2&per_page=10 Хост: https://api.directory.yandex.net Авторизация: OAuth 0c4181a7c2cf4521964a72ff57a34a07 Идентификатор X-организации: 000 Принять: приложение/json Идентификатор X-запроса: 123456
Была ли статья полезна?
Примеры использования API.
Описание APIВнимание. Яндекс Коннект больше не поддерживается. API каталога будет закрыт с 01 марта 2023 г.
Для управления организациями, пользователями и доменами перейдите в Яндекс 360 для бизнеса.
Документация по API 360 (на русском языке)
В этом разделе приведены примеры доступа к Directory API с помощью простых скриптов Python.
Для правильной работы этих примеров настройте среду:
Зарегистрируйте свое приложение на OAuth-сервере Яндекса и получите токен доступа.
Поместите токен в переменную среды
TOKEN.В рабочем каталоге создайте CSV-файлы, содержащие данные отдела и сотрудника:
отделы.csv :
label,name,parentacc, Accounting,management, Management,sales, Sales,sales-msk, Moscow Sales , Salessales-spb, Санкт-Петербург Продажи, Salestech, IT,бэкофис, Backoffice Development, IThelpdesk, Helpdesk, IT
users.
csv :псевдоним, имя, фамилия, Departmentjohn.s, John, Smith, Managementstar, Jane, Brown, Accountingpeter.g, Peter, Moore, Backoffice development
Вы можете использовать это скрипт для создания нескольких новых отделов. Их параметры указаны в файле Departments.csv .
#!/usr/bin/env python# coding: utf-8import osimport csvimport sysimport requestTOKEN = os.environ.get('TOKEN')USER_AGENT = 'Пример синхронизации каталога'def load_departments(filename): """Читает CSV-файл с данными отдела и возвращает итерируемый объект для включения итерации по словарям, содержащим данные отдела. ) yield from rowsdef create_department(data, уже_создано): """Создает отдел в Справочнике и возвращает его идентификатор.
Принимает словарь в качестве входных данных: { 'label': 'краткое английское название списка рассылки', 'name': 'название отдела', 'parent': 'название родительского отдела или пустая строка', } And Dictionary {'Название отдела ': id_from_directory}, который можно использовать для поиска идентификатора родительского отдела в Каталоге.
""" имя = данные ['имя'].strip() родитель = данные ['родитель'].strip() метка = данные ['метка'].strip() если родитель: если родитель еще не создан: поднять RuntimeError ( 'Отдел {родительский} должен предшествовать ' ' {текущий} отдел в данных'.format(родитель=родитель, текущий=имя, )) parent_id = уже_создан[родительский] else: # Если родительский отдел не указан, # создать в «корневом» отделе. : USER_AGENT, } response = request.post( 'https://api.directory.yandex.net/v6/departments/', json=payload, headers=headers, timeout=10, ) # При возникновении ошибки генерировать исключение .response.raise_for_status() # Если все Хорошо, верни ID. response_data = response.json() return response_data ['id']def load_already_created(): """Извлекает данные о существующих отделах из Справочника и возвращает словарь {'Название отдела': Department_id} """ params = { 'fields' : 'name', } headers = { 'Авторизация': 'OAuth' + TOKEN, 'User-Agent': USER_AGENT, } # Для простоты игнорируем тот факт, что # может быть больше 20 отделов, # которые не все умещается в один запрос.
В реальном коде вам нужно # распарсить ключ ссылки и сделать дополнительные запросы. response = request.get( 'https://api.directory.yandex.net/v6/departments/', params=params, headers=headers, timeout=10, ) response.raise_for_status() response_data = response.json() results = response_data ['result'] results = { отдел ['имя']: отдел ['идентификатор'] для отдела в результатах } return resultsdef create_departments(filename): """Читает данные из файла и создает структуру отдела. """ отделы = load_departments(имя файла) уже_создано = load_already_created() для элемента в отделах: name = item ['name'].strip() # Отдел создается только в том случае, если # отдел с таким именем не существует, если имя не в уже_создано: dep_id = create_department(элемент, уже_создано) уже_создано[имя] = dep_idif __name__ == '__main__': if len(sys.argv) != 2: print('Использование: {0} отделов.csv'.format( sys.argv[0])) sys.exi t(1) иначе: create_departments(sys.argv[1]) Вы можете использовать скрипт для добавления новых сотрудников.
Их параметры указаны в файле users.csv .
#!/usr/bin/env python# coding: utf-8import osimport csvimport sysimport stringimport randomimport requestTOKEN = os.environ.get('TOKEN')USER_AGENT = 'Пример синхронизации каталога'def load_users(filename): """ Читает CSV-файл с информацией о сотрудниках и возвращает итерируемый объект, который можно использовать для перебора словарей, содержащих данные о сотрудниках. csv.DictReader(csvfile) yield from rowsdef create_user(данные, отделы): """Создает пользователя в Каталоге.
Принимает словарь: { 'псевдоним': 'Логин сотрудника', 'первый': 'Имя', 'последний': 'Фамилия', 'отдел': 'название отдела или пустая строка', } Второй аргумент - словарь {' Название отдела':department_id}.
Вам нужен словарь, чтобы определить идентификатор отдела, в котором вы создаете сотрудника. """ data = {ключ: value.strip() для ключа, значение в data.items() } имя_отдела = данные['отдел'] если имя_отдела: если имя_отдела не в отделах: поднять RuntimeError('Отдел "{0} " не найден'.
format(department_name))department_id=departments[department_name] else: # Если отдел не указан, сотрудник # создается на высшем уровне. Department_id = 1 payload = { 'nickname': data[ 'псевдоним'], 'имя': {'первый': данные ['первый'], 'последний': данные ['последний']}, 'department_id': 'department_id', 'пароль': данные ['пароль'], } headers = { 'Авторизация': 'OAuth' + TOKEN, 'User-Agent': USER_AGENT, } response = request.post( 'https://api.directory.yandex.net/v6/users/', json= payload, headers=headers, timeout=10, ) # Если произошла ошибка, выдать исключение response.raise_for_status() # Если e все в порядке, верните удостоверение личности. response_data = response.json() return response_data['id']def get_departments(): """Извлекает данные об уже существующих отделах из Справочника и возвращает словарь {'Название отдела': Department_id} """ params = { 'fields ':'name', } headers = { 'Authorization': 'OAuth' + TOKEN, 'User-Agent': USER_AGENT, } # Для простоты игнорируем тот факт, # что отделов может быть больше 20, поэтому они выиграли не помещается # в один запрос.
В реальном коде вам нужно # распарсить ключ ссылки и сделать дополнительные запросы. response = request.get( 'https://api.directory.yandex.net/v6/departments/', params=params, headers=headers, timeout=10, ) response.raise_for_status() response_data = response.json() результаты = response_data['результат'] результаты = {отдел ['имя']: отдел ['идентификатор'] для отдела в результатах } return resultsdef create_random_password (длина = 10): символы = string.ascii_letters + string.digits return". join( random.choice(symbols) for i in range(length))def load_already_created(): """Он берет данные о существующих сотрудниках из Справочника и возвращает набор логинов. """ params = { 'fields': 'nickname', } headers = { 'Authorization': 'OAuth' + TOKEN, 'User-Agent': USER_AGENT, } # Для простоты игнорируем тот факт, # что может быть больше 20 сотрудников, поэтому в # один запрос они не влезут. В реальном коде здесь нужно будет # распарсить ключ ссылок и сделать дополнительные запросы. response = request.
get( 'https://api.directory .yandex.net/v6/users/', params=params, headers=headers, timeout=10, ) response.raise_for_status() response_data = response.json() results = response_data ['result'] return {user['nickname '] для пользователя в результатах}def create_users(filename, output): """Читает данные из файла и создает пользователей.
""" # Убедимся, что выходной файл не существует, # иначе мы можем случайно # стереть пароли сотрудников, зарегистрированных # во время предыдущего запуска скрипта. {0} существует. Пожалуйста, выберите другое имя файла.') users_data = load_users(filename) Departments = get_departments() уже_created = load_already_created() # Здесь мы сохраняем имена пользователей и пароли созданных сотрудников # чтобы записать их в выходной файл позже new_users = [] для элемента в user_data: try: псевдоним = элемент['псевдоним'].strip() # Мы создадим сотрудника, только если нет # сотрудника с таким именем пользователя, если псевдоним отсутствует в уже_созданном: элемент['пароль '] = create_random_password() create_user(элемент, отделы) new_users.
