Управление целевыми профилямиManage targeting profiles

Используйте эти методы в API рекламных акций Microsoft Store для выбора пользователей, регионов и типов продуктов, по которым вы хотите производить таргетинг для каждой линии поставки в рекламной кампании.Use these methods in the Microsoft Store promotions API to select the users, geographies and inventory types that you want to target for each delivery line in a promotional ad campaign. Профили таргетинга можно создавать и повторно использовать для нескольких линий поставки.Targeting profiles can be created and reused across multiple delivery lines.

Дополнительные сведения о связи между целевыми профилями и рекламными кампаниями, каналами доставки и рекламными материалами см. в разделе Проведение рекламных кампаний с помощью служб Microsoft Store.For more information about the relationship between targeting profiles and ad campaigns, delivery lines, and creatives, see Run ad campaigns using Microsoft Store services.

Предварительные условияPrerequisites

Для использования этих методов сначала необходимо сделать следующее.To use these methods, you need to first do the following:

  • Если вы еще не сделали этого, выполните все необходимые условия для API рекламных акций Microsoft Store.If you have not done so already, complete all the prerequisites for the Microsoft Store promotions API.
  • Получите маркер доступа Azure AD, который будет использоваться в заголовке запроса этих методов.Obtain an Azure AD access token to use in the request header for these methods. После получения токена доступа у вас будет 60 минут, чтобы использовать его до окончания его срока действия.After you obtain an access token, you have 60 minutes to use it before it expires. После истечения срока действия токена можно получить новый токен.After the token expires, you can obtain a new one.

ЗапросRequest

Эти методы имеют следующие URI.These methods have the following URIs.

Тип методаMethod type Универсальный код ресурса (URI) запросаRequest URI ОписаниеDescription
POSTPOST https://manage.devcenter.microsoft.com/v1.0/my/promotion/targeting-profile Создает новый профиль таргетинга.Creates a new targeting profile.
PUTPUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/targeting-profile/{targetingProfileId} Редактирует профиль таргетинга, заданный targetingProfileId.Edits the targeting profile specified by targetingProfileId.
GETGET https://manage.devcenter.microsoft.com/v1.0/my/promotion/targeting-profile/{targetingProfileId} Получает профиль таргетинга, заданный targetingProfileId.Gets the targeting profile specified by targetingProfileId.
ЗаголовокHeader ТипType ОписаниеDescription
AuthorizationAuthorization Строкаstring Обязательный.Required. Маркер доступа Azure AD в форме носителя < маркера>.The Azure AD access token in the form Bearer <token>.
Tracking IDTracking ID Код GUIDGUID Необязательно.Optional. Идентификатор, который отслеживает поток вызовов.An ID that tracks the call flow.

Тело запросаRequest body

Методы POST и PUT требуют использовать тело запроса JSON с обязательными полями объекта Профиль таргетинга и любыми другими полями, которые вы хотите установить или изменить.The POST and PUT methods require a JSON request body with the required fields of a Targeting profile object and any additional fields you want to set or change.

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

Следующий пример демонстрирует вызов метода POST для создания профиля таргетинга.The following example demonstrates how to call the POST method to create a targeting profile.

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

{
    "name": "Contoso App Campaign - Targeting Profile 1",
    "targetingType": "Manual",
    "age": [
      651,
      652],
    "gender": [
      700
    ],
    "country": [
      11,
      12
    ],
    "osVersion": [
      504
    ],
    "deviceType": [
      710
    ],
    "supplyType": [
      11470
    ]
}

Следующий пример демонстрирует вызов метода GET для получения профиля таргетинга.The following example demonstrates how to call the GET method to retrieve a targeting profile.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/targeting-profile/310023951  HTTP/1.1
Authorization: Bearer <your access token>

ОтветResponse

Эти методы возвращают тело ответа JSON с объектом Профиль таргетинга, содержащим сведения о профиле таргетинга, который был создан, обновлен или получен.These methods return a JSON response body with a Targeting profile object that contains information about the targeting profile that was created, updated, or retrieved. В следующем примере показано тело ответа для этих методов.The following example demonstrates a response body for these methods.

{
  "Data": {
    "id": 310021746,
    "name": "Contoso App Campaign - Targeting Profile 1",
    "targetingType": "Manual",
    "age": [
      651,
      652
    ],
    "gender": [
      700
    ],
    "country": [
      6,
      13,
      29
    ],
    "osVersion": [
      504,
      505,
      506,
      507,
      508
    ],
    "deviceType": [
      710,
      711
    ],
    "supplyType": [
      11470
    ]
  }
}

Объект профиля таргетингаTargeting profile object

Для этих методов тела запроса и ответа содержат следующие поля.The request and response bodies for these methods contain the following fields. В этой таблице показаны поля, которые доступны только для чтения (это означает, что они не могут изменяться в методе PUT), и поля, которые необходимы в теле запроса для метода POST.This table shows which fields are read-only (meaning that they cannot be changed in the PUT method) and which fields are required in the request body for the POST method.

ПолеField ТипType ОписаниеDescription Только чтениеRead only По умолчаниюDefault Обязательный для POSTRequired for POST
idid целое числоinteger Идентификатор профиля таргетинга.The ID of the targeting profile. ДаYes НетNo
namename Строкаstring Имя профиля таргетинга.The name of the targeting profile. НетNo ДаYes
targetingTypetargetingType Строкаstring Принимает одно из следующих значений:One of the following values:
  • Автоматически. Укажите это значение, чтобы разрешить корпорации Майкрософт выбрать профиль выбора целевой платформы на основе параметров для приложения в центре партнеров.Auto: Specify this value to allow Microsoft to choose the targeting profile based on the settings for your app in Partner Center.
  • Вручную. Укажите это значение, чтобы определять свои собственные, предназначенных для профиля.Manual: Specify this value to define your own targeting profile.
НетNo Auto (Автоматически)Auto ДаYes
ageage Массивarray Одно или несколько целых чисел, определяющих возрастные диапазоны интересующих вас пользователей.One or more integers that identify the age ranges of the users to target. Полный список целых чисел см. в разделе Значения возраста в этой статье.For a complete list of integers, see Age values in this article. НетNo nullnull НетNo
gendergender Массивarray Одно или несколько целых чисел, которые определяют пол интересующих вас пользователей.One or more integers that identify the genders of the users to target. Полный список целых чисел см. в разделе Значения пола в этой статье.For a complete list of integers, see Gender values in this article. НетNo nullnull НетNo
countrycountry Массивarray Одно или несколько целых чисел, определяющих коды стран интересующих вас пользователей.One or more integers that identify the country codes of the users to target. Полный список целых чисел см. в разделе Значения кодов стран в этой статье.For a complete list of integers, see Country code values in this article. НетNo nullnull НетNo
osVersionosVersion Массивarray Одно или несколько целых чисел, определяющих версии ОС интересующих вас пользователей.One or more integers that identify the OS versions of the users to target. Полный список целых чисел см. в разделе Значения версий ОС в этой статье.For a complete list of integers, see OS version values in this article. НетNo nullnull НетNo
deviceTypedeviceType Массивarray Одно или несколько целых чисел, определяющих типы устройств интересующих вас пользователей.One or more integers that identify the device types of the users to target. Полный список целых чисел см. в разделе Значения типов устройств в этой статье.For a complete list of integers, see Device type values in this article. НетNo nullnull НетNo
supplyTypesupplyType Массивarray Одно или несколько целых чисел, которые определяют тип продуктов, в которых будут отображаться объявления кампании.One or more integers that identify the type of inventory where the campaign's ads will be shown. Полный список целых чисел см. в разделе Значения типов поставки в этой статье.For a complete list of integers, see Supply type values in this article. НетNo nullnull НетNo

Значения возрастаAge values

Поле age в объекте TargetingProfile содержит одно или несколько из перечисленных ниже целых чисел, которые обозначают возрастные диапазоны интересующих вас пользователей.The age field in the TargetingProfile object contains one or more of the following integers that identify the age ranges of the users to target.

Целое число для поля ageInteger value for age field Соответствующая возрастная категорияCorresponding age range
651651 13–1713 to 17
652652 18–2418 to 24
653653 25–3425 to 34
654654 35–4935 to 49
655655 50 и старше50 and above

Для получения поддерживаемых значений поля age программными средствами можно вызвать следующий метод GET.To get the supported values for the age field programmatically, you can call the following GET method. Для Authorization заголовок, передайте маркер доступа Azure AD в форме носителя < маркера>.For the Authorization header, pass your Azure AD access token in the form Bearer <token>.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/reference/age
Authorization: Bearer <your access token>

В примере ниже показано тело ответа для этого метода.The following example shows the response body for this method.

{
  "Data": {
    "Age": {
      "651": "Age13To17",
      "652": "Age18To24",
      "653": "Age25To34",
      "654": "Age35To49",
      "655": "Age50AndAbove"
    }
  }
}

Значения полаGender values

Поле gender в объекте TargetingProfile содержит одно или несколько из перечисленных ниже целых чисел, которые обозначают пол интересующих вас пользователей.The gender field in the TargetingProfile object contains one or more of the following integers that identify the genders of the users to target.

Целое число для поля genderInteger value for gender field Соответствующий полCorresponding gender
700700 МужскойMale
701701 ЖенскийFemale

Для получения поддерживаемых значений поля gender программными средствами можно вызвать следующий метод GET.To get the supported values for the gender field programmatically, you can call the following GET method. Для Authorization заголовок, передайте маркер доступа Azure AD в форме носителя < маркера>.For the Authorization header, pass your Azure AD access token in the form Bearer <token>.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/reference/gender
Authorization: Bearer <your access token>

В примере ниже показано тело ответа для этого метода.The following example shows the response body for this method.

{
  "Data": {
    "Gender": {
      "700": "Male",
      "701": "Female"
    }
  }
}

Значения версии ОСOS version values

Поле osVersion в объекте TargetingProfile содержит одно или несколько из перечисленных ниже целых чисел, которые обозначают версии ОС интересующих вас пользователей.The osVersion field in the TargetingProfile object contains one or more of the following integers that identify the OS versions of the users to target.

Целое число для поля osVersionInteger value for osVersion field Соответствующая версия операционной системыCorresponding OS version
500500 Windows Phone 7Windows Phone 7
501501 Windows Phone 7.1Windows Phone 7.1
502502 Windows Phone 7.5Windows Phone 7.5
503503 Windows Phone 7.8Windows Phone 7.8
504504 Windows Phone 8.0Windows Phone 8.0
505505 Windows Phone 8.1Windows Phone 8.1
506506 Windows 8.0Windows 8.0
507507 Windows 8.1Windows 8.1
508508 Windows 10Windows 10
509509 Windows 10 MobileWindows 10 Mobile

Для получения поддерживаемых значений поля osVersion программными средствами можно вызвать следующий метод GET.To get the supported values for the osVersion field programmatically, you can call the following GET method. Для Authorization заголовок, передайте маркер доступа Azure AD в форме носителя < маркера>.For the Authorization header, pass your Azure AD access token in the form Bearer <token>.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/reference/osversion
Authorization: Bearer <your access token>

В примере ниже показано тело ответа для этого метода.The following example shows the response body for this method.

{
  "Data": {
    "OsVersion": {
      "500": "WindowsPhone70",
      "501": "WindowsPhone71",
      "502": "WindowsPhone75",
      "503": "WindowsPhone78",
      "504": "WindowsPhone80",
      "505": "WindowsPhone81",
      "506": "Windows80",
      "507": "Windows81",
      "508": "Windows10",
      "509": "WindowsPhone10"
    }
  }
}

Значения типа устройстваDevice type values

Поле deviceType в объекте TargetingProfile содержит одно или несколько из перечисленных ниже целых чисел, которые обозначают типы устройств интересующих вас пользователей.The deviceType field in the TargetingProfile object contains one or more of the following integers that identify the device types of the users to target.

Целое число для поля deviceTypeInteger value for deviceType field Соответствующий тип устройстваCorresponding device type ОписаниеDescription
710710 WindowsWindows Это обозначает устройства под управлением настольных версий Windows 10 или Windows 8.x.This represents devices running a desktop version of Windows 10 or Windows 8.x.
711711 ТелефонPhone Это обозначает устройства под управлением Windows 10 Mobile, Windows Phone 8.x и Windows Phone 7.x.This represents devices running Windows 10 Mobile, Windows Phone 8.x, or Windows Phone 7.x.

Для получения поддерживаемых значений поля deviceType программными средствами можно вызвать следующий метод GET.To get the supported values for the deviceType field programmatically, you can call the following GET method. Для Authorization заголовок, передайте маркер доступа Azure AD в форме носителя < маркера>.For the Authorization header, pass your Azure AD access token in the form Bearer <token>.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/reference/devicetype
Authorization: Bearer <your access token>

В примере ниже показано тело ответа для этого метода.The following example shows the response body for this method.

{
  "Data": {
    "DeviceType": {
      "710": "Windows",
      "711": "Phone"
    }
  }
}

Значения типа поставкиSupply type values

Поле SupplyType в объекте TargetingProfile содержит одно или несколько из следующих целых чисел, указывающих тип продуктов, где будут отображаться объявления кампании.The supplyType field in the TargetingProfile object contains one or more of the following integers that identify the type of inventory where the campaign's ads will be shown.

Целое число для поля supplyTypeInteger value for supplyType field Соответствующий тип поставкиCorresponding supply type ОписаниеDescription
1147011470 ПриложениеApp Это относится к рекламным объявлениям, которые отображаются только в приложениях.This refers to ads that appear in apps only.
1147111471 УниверсальныйUniversal Этот тип относится к рекламным объявлениям, которые появляются в приложениях, в Интернете и на других поверхностях отображения.This refers to ads that appear in apps, on the Web, and on and other display surfaces.

Для получения поддерживаемых значений поля supplyType программными средствами можно вызвать следующий метод GET.To get the supported values for the supplyType field programmatically, you can call the following GET method. Для Authorization заголовок, передайте маркер доступа Azure AD в форме носителя < маркера>.For the Authorization header, pass your Azure AD access token in the form Bearer <token>.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/reference/supplytype
Authorization: Bearer <your access token>

В примере ниже показано тело ответа для этого метода.The following example shows the response body for this method.

{
  "Data": {
    "SupplyType": {
      "11470": "App",
      "11471": "Universal"
    }
  }
}

Значения кода страныCountry code values

Поле country в объекте TargetingProfile содержит одно или несколько из следующих целых чисел, которые указывают коды стран ISO 3166-1 alpha-2 интересующих вас пользователей.The country field in the TargetingProfile object contains one or more of the following integers that identify the ISO 3166-1 alpha-2 country codes of the users to target.

Целое число для поля countryInteger value for country field Соответствующий код страныCorresponding country code
11 СШАUS
22 AUAU
33 ATAT
44 BEBE
55 BRBR
66 CACA
77 DKDK
88 FIFI
99 FRFR
1010 DEDE
1111 GRGR
1212 HKHK
1313 ININ
1414 IEIE
1515 ИТ-отделIT
1616 JPJP
1717 LULU
1818 MXMX
1919 NLNL
2020 NZNZ
2121 НЕТNO
2222 PLPL
2323 PTPT
2424 SGSG
2525 ESES
2626 SESE
2727 CHCH
2828 TWTW
2929 ГБGB
3030 RURU
3131 CLCL
3232 COCO
3333 CZCZ
3434 HUHU
3535 ZAZA
3636 KRKR
3737 CNCN
3838 RORO
3939 TRTR
4040 SKSK
4141 ILIL
4242 IDID
4343 ARAR
4444 MYMY
4545 PHPH
4646 PEPE
4747 UAUA
4848 AEAE
4949 THTH
5050 IQIQ
5151 VNVN
5252 CRCR
5353 VEVE
5454 QAQA
5555 SISI
5656 BGBG
5757 LTLT
5858 RSRS
5959 Отдел кадровHR
6060 Отдел кадровHR
6161 LVLV
6262 EEEE
6363 ISIS
6464 KZKZ
6565 SASA
6767 ALAL
6868 DZDZ
7070 AOAO
7272 AMAM
7373 AZAZ
7474 BSBS
7575 BDBD
7676 BBBB
7777 BYBY
8181 BOBO
8282 BABA
8383 BWBW
8787 KHKH
8888 CMCM
9494 CDCD
9595 CICI
9696 CYCY
9999 DODO
100100 ECEC
101101 EGEG
102102 SVSV
107107 FJFJ
108108 GAGA
110110 GEGE
111111 GHGH
114114 GTGT
118118 HTHT
119119 HNHN
120120 JMJM
121121 JOJO
122122 KEKE
124124 KWKW
125125 KGKG
126126 LALA
127127 LBLB
133133 MKMK
135135 MWMW
138138 MTMT
141141 MUMU
145145 MEME
146146 MAMA
147147 MZMZ
148148 Н/ДNA
150150 NPNP
151151 NINI
153153 NGNG
154154 OMOM
155155 PKPK
157157 PAPA
159159 PYPY
167167 SNSN
172172 LKLK
176176 TZTZ
180180 TTTT
181181 TNTN
184184 UGUG
185185 UYUY
186186 UZUZ
189189 ZMZM
190190 ZWZW
219219 MDMD
224224 PSPS
225225 RERE
246246 PRPR

Для получения поддерживаемых значений поля country программными средствами можно вызвать следующий метод GET.To get the supported values for the country field programmatically, you can call the following GET method. Для Authorization заголовок, передайте маркер доступа Azure AD в форме носителя < маркера>.For the Authorization header, pass your Azure AD access token in the form Bearer <token>.

GET https://manage.devcenter.microsoft.com/v1.0/my/promotion/reference/country
Authorization: Bearer <your access token>

В примере ниже показано тело ответа для этого метода.The following example shows the response body for this method.

{
  "Data": {
    "Country": {
      "1": "US",
      "2": "AU",
      "3": "AT",
      "4": "BE",
      "5": "BR",
      "6": "CA",
      "7": "DK",
      "8": "FI",
      "9": "FR",
      "10": "DE",
      "11": "GR",
      "12": "HK",
      "13": "IN",
      "14": "IE",
      "15": "IT",
      "16": "JP",
      "17": "LU",
      "18": "MX",
      "19": "NL",
      "20": "NZ",
      "21": "NO",
      "22": "PL",
      "23": "PT",
      "24": "SG",
      "25": "ES",
      "26": "SE",
      "27": "CH",
      "28": "TW",
      "29": "GB",
      "30": "RU",
      "31": "CL",
      "32": "CO",
      "33": "CZ",
      "34": "HU",
      "35": "ZA",
      "36": "KR",
      "37": "CN",
      "38": "RO",
      "39": "TR",
      "40": "SK",
      "41": "IL",
      "42": "ID",
      "43": "AR",
      "44": "MY",
      "45": "PH",
      "46": "PE",
      "47": "UA",
      "48": "AE",
      "49": "TH",
      "50": "IQ",
      "51": "VN",
      "52": "CR",
      "53": "VE",
      "54": "QA",
      "55": "SI",
      "56": "BG",
      "57": "LT",
      "58": "RS",
      "59": "HR",
      "60": "BH",
      "61": "LV",
      "62": "EE",
      "63": "IS",
      "64": "KZ",
      "65": "SA",
      "67": "AL",
      "68": "DZ",
      "70": "AO",
      "72": "AM",
      "73": "AZ",
      "74": "BS",
      "75": "BD",
      "76": "BB",
      "77": "BY",
      "81": "BO",
      "82": "BA",
      "83": "BW",
      "87": "KH",
      "88": "CM",
      "94": "CD",
      "95": "CI",
      "96": "CY",
      "99": "DO",
      "100": "EC",
      "101": "EG",
      "102": "SV",
      "107": "FJ",
      "108": "GA",
      "110": "GE",
      "111": "GH",
      "114": "GT",
      "118": "HT",
      "119": "HN",
      "120": "JM",
      "121": "JO",
      "122": "KE",
      "124": "KW",
      "125": "KG",
      "126": "LA",
      "127": "LB",
      "133": "MK",
      "135": "MW",
      "138": "MT",
      "141": "MU",
      "145": "ME",
      "146": "MA",
      "147": "MZ",
      "148": "NA",
      "150": "NP",
      "151": "NI",
      "153": "NG",
      "154": "OM",
      "155": "PK",
      "157": "PA",
      "159": "PY",
      "167": "SN",
      "172": "LK",
      "176": "TZ",
      "180": "TT",
      "181": "TN",
      "184": "UG",
      "185": "UY",
      "186": "UZ",
      "189": "ZM",
      "190": "ZW",
      "219": "MD",
      "224": "PS",
      "225": "RE",
      "246": "PR"
    }
  }
}