Поделиться через

Управление рекламными кампаниями

  • Статья

Используйте эти методы в API рекламных акций Microsoft Store для создания, редактирования и получения рекламных рекламных кампаний для вашего приложения. Каждая кампания, созданная с помощью этого метода, может быть связана только с одним приложением.

Примечание. Вы также можете создавать рекламные кампании и управлять ими с помощью Центра партнеров, а также кампании, которые вы создаете программным способом, можно получить в Центре партнеров. Дополнительные сведения об управлении рекламными кампаниями в Центре партнеров см. в статье "Создание рекламной кампании для вашего приложения".

При использовании этих методов для создания или обновления кампании обычно вызывается один или несколько следующих методов для управления линиями доставки, целевыми профилями и творческими объектами, связанными с кампанией. Дополнительные сведения о связи между кампаниями, линиями доставки, профилями целевого назначения и творческими решениями см. в статье "Запуск рекламных кампаний с помощью служб Microsoft Store".

Необходимые компоненты

Чтобы использовать эти методы, сначала необходимо выполнить следующие действия:

  • Если вы этого еще не сделали, выполните все предварительные требования для API рекламных акций Microsoft Store.

    Обратите внимание , что в рамках предварительных требований необходимо создать по крайней мере одну платную рекламную кампанию в Центре партнеров и добавить по крайней мере один инструмент оплаты для рекламной кампании в Центре партнеров. Линии доставки для рекламных кампаний, создаваемых с помощью этого API, автоматически выставляют счета за инструмент оплаты по умолчанию, выбранный на странице рекламных кампаний в Центре партнеров.

  • Получите маркер доступа Azure AD для использования в заголовке запроса для этих методов. После получения маркера доступа у вас будет 60 минут, чтобы использовать его до истечения срока действия. После истечения срока действия маркера можно получить новый.

Запросить

Эти методы имеют следующие URI.

Тип метода URI запроса Description
POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign Создает новую рекламную кампанию.
PUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} Изменяет рекламную кампанию, указанную в кампанииId.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/{campaignId} Возвращает рекламную кампанию, указанную в кампанииId.
GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign Запросы к рекламным кампаниям. См. раздел "Параметры" для поддерживаемых параметров запроса.
Верхний колонтитул Тип Описание
Авторизация строка Обязательный. Маркер доступа Azure AD в маркере> носителя<формы.
Идентификатор отслеживания GUID Необязательно. Идентификатор, отслеживающий поток вызовов.

 

Параметры

Метод GET для запроса рекламных кампаний поддерживает следующие необязательные параметры запроса.

Имя. Тип Описание
skip INT Количество строк, пропускаемых в запросе. Используйте этот параметр для страницы с помощью наборов данных. Например, получение=10 и skip=0 извлекает первые 10 строк данных, top=10 и skip=10 извлекает следующие 10 строк данных и т. д.
fetch INT Количество строк данных, возвращаемых в запросе.
campaignSetSortColumn строка Упорядочивает объекты кампании в тексте ответа по указанному полю. Синтаксис — CampaignSetSortColumn=field, где параметр поля может быть одной из следующих строк:

  • id
  • createdDateTime

Значение по умолчанию создаетсяDateTime.
isDescending Логический Сортирует объекты кампании в теле отклика в порядке убывания или возрастания.
storeProductId строка Используйте это значение для возврата только рекламных кампаний, связанных с приложением с указанным идентификатором Магазина. Пример идентификатора магазина для продукта — 9nblggh42cfd.
label строка Используйте это значение для возврата только рекламных кампаний, которые включают указанную метку в объект Кампании .

Текст запроса

Для методов POST и PUT требуется текст запроса JSON с обязательными полями объекта Кампании и любыми дополнительными полями, которые необходимо задать или изменить.

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

В следующем примере показано, как вызвать метод POST для создания рекламной кампании.

POST https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign HTTP/1.1
Authorization: Bearer <your access token>

{
    "name": "Contoso App Campaign",
    "storeProductId": "9nblggh42cfd",
    "configuredStatus": "Active",
    "objective": "DriveInstalls",
    "type": "Community"
}

В следующем примере показано, как вызвать метод GET для получения определенной рекламной кампании.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign/31043481  HTTP/1.1
Authorization: Bearer <your access token>

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

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/campaign?storeProductId=9nblggh42cfd&fetch=100&skip=0&campaignSetSortColumn=createdDateTime HTTP/1.1
Authorization: Bearer <your access token>

Response

Эти методы возвращают текст ответа JSON с одним или несколькими объектами кампании в зависимости от вызываемого метода. В следующем примере показан текст ответа для метода GET для конкретной кампании.

{
    "Data": {
        "id": 31043481,
        "name": "Contoso App Campaign",
        "createdDate": "2017-01-17T10:12:15Z",
        "storeProductId": "9nblggh42cfd",
        "configuredStatus": "Active",
        "effectiveStatus": "Active",
        "effectiveStatusReasons": [
            "{\"ValidationStatusReasons\":null}"
        ],
        "labels": [],
        "objective": "DriveInstalls",
        "type": "Paid",
        "lines": [
            {
                "id": 31043476,
                "name": "Contoso App Campaign - Paid Line"
            }
        ]
    }
}

Объект Кампании

Тела запросов и ответов для этих методов содержат следующие поля. В этой таблице показано, какие поля доступны только для чтения (это означает, что они не могут быть изменены в методе PUT) и какие поля необходимы в тексте запроса для метода POST.

Поле Тип Описание Только чтение По умолчанию. Требуется для POST
id integer Идентификатор рекламной кампании. Да Нет
name строка Имя рекламной кампании. No Да
configuredStatus строка Одно из следующих значений, указывающее состояние рекламной кампании, указанной разработчиком:
  • Активные
  • Неактивный
 No Активен Да
effectiveStatus строка Одно из следующих значений, указывающее эффективное состояние рекламной кампании на основе проверки системы:
  • Активные
  • Неактивный
  • Обработка
 Да Нет
effectiveStatusReasons array Одно или несколько следующих значений, которые указывают причину эффективного состояния рекламной кампании:
  • AdCreativesInactive
  • BillingFailed
  • AdLinesInactive
  • ValidationFailed
  • Неудачно
 Да Нет
storeProductId строка Идентификатор Магазина для приложения, с которым связана эта рекламная кампания. Пример идентификатора магазина для продукта — 9nblggh42cfd. Да Да
меток. array Одна или несколько строк, представляющих пользовательские метки для кампании. Эти метки используются для поиска и добавления тегов в кампании. No null No
type строка Одно из следующих значений, указывающее тип кампании:
  • Оплачиваемый
  • Дом
  • Сообщество
 Да Да
objective. строка Одно из следующих значений, указывающее цель кампании:
  • DriveInstall
  • DriveReengagement
  • DriveInAppPurchase
 No DriveInstall Да
lines array Один или несколько объектов, определяющих линии доставки, связанные с рекламной кампанией. Каждый объект в этом поле состоит из поля идентификатора и имени, указывающего идентификатор и имя строки доставки. No No
createdDate строка Дата и время создания рекламной кампании в формате ISO 8601. Да Нет