Gerenciar perfis de direcionamentoManage targeting profiles

Use esses métodos na API de promoções da Microsoft Store para selecionar usuários, regiões geográficas e tipos de inventário que você deseja destinar para cada linha de entrega de uma campanha publicitária promocional.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. Os perfis de direcionamento podem ser criados e reutilizados em diversas linhas de entrega.Targeting profiles can be created and reused across multiple delivery lines.

Para saber mais sobre a relação entre perfis de direcionamento e campanhas publicitárias, linhas de entrega e criativos, consulte Veicular campanhas publicitárias usando serviços da 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.

Pré-requisitosPrerequisites

Para usar esses métodos, primeiro você precisa do seguinte:To use these methods, you need to first do the following:

  • Se você não tiver feito isso, conclua todos os pré-requisitos da API de promoções da Microsoft Store.If you have not done so already, complete all the prerequisites for the Microsoft Store promotions API.
  • Obtenha um token de acesso do Azure AD para usar no cabeçalho da solicitação desses métodos.Obtain an Azure AD access token to use in the request header for these methods. Depois de obter um token de acesso, você terá 60 minutos para usá-lo antes que ele expire.After you obtain an access token, you have 60 minutes to use it before it expires. Depois que o token expirar, você poderá obter um novo.After the token expires, you can obtain a new one.

SolicitaçãoRequest

Esses métodos têm os seguintes URIs.These methods have the following URIs.

Tipo de métodoMethod type URI da solicitaçãoRequest URI DescriçãoDescription
POSTPOST https://manage.devcenter.microsoft.com/v1.0/my/promotion/targeting-profile Cria um novo perfil de direcionamento.Creates a new targeting profile.
PUTPUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/targeting-profile/{targetingProfileId} Edita o perfil de direcionamento especificado por targetingProfileId.Edits the targeting profile specified by targetingProfileId.
GETGET https://manage.devcenter.microsoft.com/v1.0/my/promotion/targeting-profile/{targetingProfileId} Obtém o perfil de direcionamento especificado por targetingProfileId.Gets the targeting profile specified by targetingProfileId.
CabeçalhoHeader TipoType DescriçãoDescription
AutorizaçãoAuthorization cadeia de caracteresstring Obrigatório.Required. O token de acesso do AD do Azure no formato portador < token>.The Azure AD access token in the form Bearer <token>.
ID de rastreamentoTracking ID GUIDGUID Opcional.Optional. Uma ID que rastreia o fluxo de chamada.An ID that tracks the call flow.

Corpo da solicitaçãoRequest body

Os métodos POST e PUT exigem um corpo da solicitação JSON com os campos obrigatórios de um objeto Perfil de direcionamento e quaisquer campos adicionais que você deseja definir ou alterar.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.

Exemplos de solicitaçãoRequest examples

O exemplo a seguir demonstra como chamar o método POST para criar um perfil de direcionamento.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
    ]
}

O exemplo a seguir demonstra como chamar o método GET para recuperar um perfil de direcionamento.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>

RespostaResponse

Esses métodos retornam um corpo de resposta JSON com um objeto Perfil de direcionamento que contém informações sobre o perfil de direcionamento criado, atualizado ou recuperado.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. O exemplo a seguir demonstra um corpo de resposta para esses métodos.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
    ]
  }
}

Objeto de direcionamento de perfilTargeting profile object

O corpo da solicitação e resposta desses métodos contêm os campos a seguir.The request and response bodies for these methods contain the following fields. Essa tabela mostra quais campos são somente de leitura (ou seja, eles não podem ser alterados no método PUT) e quais são necessários no corpo da solicitação para o método 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.

CampoField TipoType DescriçãoDescription Somente leituraRead only PadrãoDefault Obrigatório para POSTRequired for POST
idid número inteirointeger A ID do perfil de direcionamento.The ID of the targeting profile. SimYes NãoNo
namename cadeia de caracteresstring O nome do perfil de direcionamento.The name of the targeting profile. NãoNo SimYes
targetingTypetargetingType cadeia de caracteresstring Um dos seguintes valores:One of the following values:
  • Auto: Especifique esse valor para permitir que a Microsoft escolher o perfil de direcionamento com base nas configurações do aplicativo no Partner Center.Auto: Specify this value to allow Microsoft to choose the targeting profile based on the settings for your app in Partner Center.
  • Manual: Especifique esse valor para definir seu próprio perfil de destino.Manual: Specify this value to define your own targeting profile.
NãoNo AutomáticoAuto SimYes
idadeage matrizarray Um ou mais números inteiros que identificam os intervalos de idade dos usuários de destino.One or more integers that identify the age ranges of the users to target. Para obter uma lista completa de números inteiros, consulte Valores de idade neste artigo.For a complete list of integers, see Age values in this article. NãoNo nullnull NãoNo
gendergender matrizarray Um ou mais números inteiros que identificam os sexos dos usuários de destino.One or more integers that identify the genders of the users to target. Para obter uma lista completa de números inteiros, consulte Valores de sexo neste artigo.For a complete list of integers, see Gender values in this article. NãoNo nullnull NãoNo
paíscountry matrizarray Um ou mais números inteiros que identificam os códigos de país dos usuários de destino.One or more integers that identify the country codes of the users to target. Para obter uma lista completa de números inteiros, consulte Códigos de país neste artigo.For a complete list of integers, see Country code values in this article. NãoNo nullnull NãoNo
osVersionosVersion matrizarray Um ou mais números inteiros que identificam as versões do sistema operacional dos usuários de destino.One or more integers that identify the OS versions of the users to target. Para obter uma lista completa de números inteiros, consulte Valores da versão do sistema operacional neste artigo.For a complete list of integers, see OS version values in this article. NãoNo nullnull NãoNo
deviceTypedeviceType matrizarray Um ou mais números inteiros que identificam os tipos de dispositivo dos usuários de destino.One or more integers that identify the device types of the users to target. Para obter uma lista completa de números inteiros, consulte Valores do tipo de dispositivo neste artigo.For a complete list of integers, see Device type values in this article. NãoNo nullnull NãoNo
supplyTypesupplyType matrizarray Um ou mais números inteiros que identificam o tipo de inventário no qual os anúncios da campanha serão mostrados.One or more integers that identify the type of inventory where the campaign's ads will be shown. Para obter uma lista completa de números inteiros, consulte Valores do tipo de fornecimento neste artigo.For a complete list of integers, see Supply type values in this article. NãoNo nullnull NãoNo

Valores de idadeAge values

O campo idade no objeto TargetingProfile contém um ou mais dos seguintes inteiros que identificam as faixas etárias dos usuários de destino.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.

Valor inteiro do campo idadeInteger value for age field Faixa etária correspondenteCorresponding age range
651651 13 a 1713 to 17
652652 18 a 2418 to 24
653653 25 a 3425 to 34
654654 35 a 4935 to 49
655655 50 e acima50 and above

Para obter os valores aceitos pelo campo idade de modo programático, você pode chamar o método GET a seguir.To get the supported values for the age field programmatically, you can call the following GET method. Para o Authorization cabeçalho, passar o token de acesso do AD do Azure no formato portador < token>.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>

O exemplo de código a seguir mostra o corpo de resposta desse método.The following example shows the response body for this method.

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

Valores de sexoGender values

O campo sexo no objeto TargetingProfile contém um ou mais dos seguintes inteiros que identificam os sexos dos usuários de destino.The gender field in the TargetingProfile object contains one or more of the following integers that identify the genders of the users to target.

Valor inteiro do campo sexoInteger value for gender field Sexo correspondenteCorresponding gender
Etapas de resolução para o seguinte evento ID 700700 MasculinoMale
701701 FemininoFemale

Para obter os valores aceitos pelo campo sexo de modo programático, você pode chamar o método GET a seguir.To get the supported values for the gender field programmatically, you can call the following GET method. Para o Authorization cabeçalho, passar o token de acesso do AD do Azure no formato portador < token>.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>

O exemplo de código a seguir mostra o corpo de resposta desse método.The following example shows the response body for this method.

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

Valores de versão do sistema operacionalOS version values

O campo osVersion no objeto TargetingProfile contém um ou mais dos seguintes inteiros que identificam as versões do sistema operacional dos usuários de destino.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.

Valor inteiro do campo osVersionInteger value for osVersion field Versão do sistema operacional correspondenteCorresponding 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

Para obter os valores aceitos pelo campo osVersion de modo programático, você pode chamar o método GET a seguir.To get the supported values for the osVersion field programmatically, you can call the following GET method. Para o Authorization cabeçalho, passar o token de acesso do AD do Azure no formato portador < token>.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>

O exemplo de código a seguir mostra o corpo de resposta desse método.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"
    }
  }
}

Valores de tipo de dispositivoDevice type values

O campo deviceType no objeto TargetingProfile contém um ou mais dos seguintes inteiros que identificam os tipos de dispositivo dos usuários de destino.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.

Valor inteiro do campo deviceTypeInteger value for deviceType field Tipo de dispositivo correspondenteCorresponding device type DescriçãoDescription
710710 WindowsWindows Isso representa dispositivos que executam uma versão do Windows 10 ou Windows 8. x para computadores desktop.This represents devices running a desktop version of Windows 10 or Windows 8.x.
711711 PhonePhone Isso representa dispositivos que executam o Windows 10 Mobile, Windows Phone 8. x ou Windows Phone 7. x.This represents devices running Windows 10 Mobile, Windows Phone 8.x, or Windows Phone 7.x.

Para obter os valores aceitos pelo campo deviceType de modo programático, você pode chamar o método GET a seguir.To get the supported values for the deviceType field programmatically, you can call the following GET method. Para o Authorization cabeçalho, passar o token de acesso do AD do Azure no formato portador < token>.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>

O exemplo de código a seguir mostra o corpo de resposta desse método.The following example shows the response body for this method.

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

Fornecer valores de tipoSupply type values

O campo supplyType no objeto TargetingProfile contém um ou mais dos seguintes inteiros que identificam o tipo de inventário no qual os anúncios da campanha serão mostrados.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.

Valor inteiro do campo supplyTypeInteger value for supplyType field Tipo de fornecimento correspondenteCorresponding supply type DescriçãoDescription
1147011470 AplicativoApp Isso se refere aos anúncios que aparecem somente em apps.This refers to ads that appear in apps only.
1147111471 UniversalUniversal Isso se refere a anúncios que aparecem em apps, na Web e em outras superfícies de exibição.This refers to ads that appear in apps, on the Web, and on and other display surfaces.

Para obter os valores aceitos pelo campo supplyType de modo programático, você pode chamar o método GET a seguir.To get the supported values for the supplyType field programmatically, you can call the following GET method. Para o Authorization cabeçalho, passar o token de acesso do AD do Azure no formato portador < token>.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>

O exemplo de código a seguir mostra o corpo de resposta desse método.The following example shows the response body for this method.

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

Valores de código do paísCountry code values

O campo país no objeto TargetingProfile contém um ou mais dos seguintes inteiros que identificam os códigos de país ISO 3166-1 alfa-2 dos usuários de destino.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.

valor inteiro do campo paísInteger value for country field código do país correspondenteCorresponding country code
11 EUAUS
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 TIIT
1616 JPJP
1717 LULU
1818 MXMX
1919 NLNL
2020 NZNZ
2121 NÃONO
2222 PLPL
2323 PTPT
2424 SGSG
2525 ESES
2626 SESE
2727 CHCH
2828 TWTW
2929 GBGB
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 RHHR
6060 RHHR
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 N/DNA
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

Para obter os valores aceitos pelo campo país/região de modo programático, você pode chamar o método GET a seguir.To get the supported values for the country field programmatically, you can call the following GET method. Para o Authorization cabeçalho, passar o token de acesso do AD do Azure no formato portador < token>.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>

O exemplo de código a seguir mostra o corpo de resposta desse método.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"
    }
  }
}