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

  • Статья

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

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

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

Предварительные требования

Для использования этих методов сначала необходимо сделать следующее.

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

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

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

Запрос

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

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

 

Параметры

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

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

  • идентификатор
  • createdDateTime

Значение по умолчанию — createdDateTime.
isDescending Логическое Сортирует объекты Campaign в теле ответа в порядке убывания или возрастания.
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>

Ответ

Эти методы возвращают тело ответа 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"
            }
        ]
    }
}

Объект Campaign

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

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