Gestire i profili di destinazioneManage targeting profiles

Usa questi metodi nell'API delle promozioni di Microsoft Store per selezionare gli utenti, le aree geografiche e i tipi di inventario che desideri impostare come target per ogni riga di recapito in una campagna pubblicitaria promozionale.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. I profili di destinazione possono essere creati e riutilizzati in più righe di recapito.Targeting profiles can be created and reused across multiple delivery lines.

Per ulteriori informazioni sulla relazione tra profili di destinazione e campagne pubblicitarie, righe di recapito ed elementi creativi, vedi Eseguire campagne pubblicitarie tramite i servizi di 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.

PrerequisitiPrerequisites

Per usare questi metodi, devi prima eseguire le operazioni seguenti:To use these methods, you need to first do the following:

  • Se non lo hai già fatto, completa tutti i prerequisiti per l'API delle promozioni di Microsoft Store.If you have not done so already, complete all the prerequisites for the Microsoft Store promotions API.
  • Procurati un token di accesso di Azure AD da usare nell'intestazione della richiesta per questi metodi.Obtain an Azure AD access token to use in the request header for these methods. Dopo aver ottenuto un token di accesso, hai 60 minuti per usarlo prima che scada.After you obtain an access token, you have 60 minutes to use it before it expires. Dopo la scadenza del token, puoi ottenerne uno nuovo.After the token expires, you can obtain a new one.

RichiestaRequest

Questi metodi includono gli URI indicati di seguito.These methods have the following URIs.

Tipo di metodoMethod type URI richiestaRequest URI DescrizioneDescription
POSTPOST https://manage.devcenter.microsoft.com/v1.0/my/promotion/targeting-profile Crea un nuovo profilo di destinazione.Creates a new targeting profile.
PUTPUT https://manage.devcenter.microsoft.com/v1.0/my/promotion/targeting-profile/{targetingProfileId} Modifica il profilo di destinazione specificato da targetingProfileId.Edits the targeting profile specified by targetingProfileId.
GETGET https://manage.devcenter.microsoft.com/v1.0/my/promotion/targeting-profile/{targetingProfileId} Ottiene il profilo di destinazione specificato da targetingProfileId.Gets the targeting profile specified by targetingProfileId.
IntestazioneHeader TipoType DescrizioneDescription
AuthorizationAuthorization stringastring Obbligatorio.Required. Il token di accesso di Azure AD nel formato Bearer < token>.The Azure AD access token in the form Bearer <token>.
ID di tracciaTracking ID GUIDGUID Facoltativo.Optional. ID che tiene traccia del flusso delle chiamate.An ID that tracks the call flow.

Contenuto della richiestaRequest body

I metodi POST e PUT richiedono un corpo della richiesta JSON con i campi obbligatori di un oggetto Profilo di destinazione e qualsiasi altro campo aggiuntivo che desideri impostare o modificare.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.

Esempi di richiestaRequest examples

L'esempio seguente illustra come eseguire una chiamata al metodo POST per creare un profilo di destinazione.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
    ]
}

L'esempio seguente illustra come eseguire una chiamata al metodo GET per recuperare un profilo di destinazione.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>

RispostaResponse

Questi metodi restituiscono un corpo della risposta JSON con un oggetto Profilo di destinazione che contiene informazioni sul profilo di destinazione che è stato creato, aggiornato o recuperato.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. L'esempio seguente illustra il corpo della risposta per questi metodi.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
    ]
  }
}

Oggetto profilo di destinazioneTargeting profile object

I corpi della richiesta e della risposta per questi metodi contengono i campi indicati di seguito.The request and response bodies for these methods contain the following fields. Questa tabella mostra i campi di sola lettura, che quindi non possono essere modificati nel metodo PUT, e i campi obbligatori nel corpo della richiesta per il metodo 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 DescrizioneDescription Sola letturaRead only Impostazione predefinitaDefault Obbligatorio per POSTRequired for POST
IDid integerinteger ID del profilo di destinazione.The ID of the targeting profile. Yes NoNo
namename stringastring Nome del profilo di destinazione.The name of the targeting profile. NoNo Yes
targetingTypetargetingType stringastring Uno dei valori seguenti:One of the following values:
  • Automatica: Specificare questo valore per consentire a Microsoft di scegliere il profilo di destinazione basato sulle impostazioni per l'app nel centro per i Partner.Auto: Specify this value to allow Microsoft to choose the targeting profile based on the settings for your app in Partner Center.
  • Manuale: Specificare questo valore per definire il proprio profilo di destinazione.Manual: Specify this value to define your own targeting profile.
NoNo AutomaticoAuto Yes
ageage arrayarray Uno o più numeri interi che identificano gli intervalli di età degli utenti da definire come target.One or more integers that identify the age ranges of the users to target. Per un elenco completo dei numeri interi, vedi la sezione Valori di fascia d'età in questo articolo.For a complete list of integers, see Age values in this article. NoNo nullnull NoNo
gendergender arrayarray Uno o più numeri interi che identificano i due sessi degli utenti da definire come target.One or more integers that identify the genders of the users to target. Per un elenco completo dei numeri interi, vedi la sezione Valori di sesso in questo articolo.For a complete list of integers, see Gender values in this article. NoNo nullnull NoNo
countrycountry arrayarray Uno o più numeri interi che identificano i codici paese degli utenti da definire come target.One or more integers that identify the country codes of the users to target. Per un elenco completo dei numeri interi, vedi la sezione Valori di codice paese in questo articolo.For a complete list of integers, see Country code values in this article. NoNo nullnull NoNo
osVersionosVersion arrayarray Uno o più numeri interi che identificano le versioni del sistema operativo degli utenti da definire come target.One or more integers that identify the OS versions of the users to target. Per un elenco completo dei numeri interi, vedi la sezione Valori di versione SO in questo articolo.For a complete list of integers, see OS version values in this article. NoNo nullnull NoNo
deviceTypedeviceType arrayarray Uno o più numeri interi che identificano i tipi di dispositivi degli utenti da definire come target.One or more integers that identify the device types of the users to target. Per un elenco completo dei numeri interi, vedi la sezione Valori di tipo di dispositivo in questo articolo.For a complete list of integers, see Device type values in this article. NoNo nullnull NoNo
supplyTypesupplyType arrayarray Uno o più numeri interi che identificano il tipo di inventario in cui verranno visualizzati gli annunci della campagna.One or more integers that identify the type of inventory where the campaign's ads will be shown. Per un elenco completo dei numeri interi, vedi la sezione Valori di tipo di approvvigionamento in questo articolo.For a complete list of integers, see Supply type values in this article. NoNo nullnull NoNo

Valori di fascia d'etàAge values

Il campo age dell'oggetto TargetingProfile contiene uno o più dei seguenti valori interi che identificano le fasce d'età degli utenti da definire come target.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.

Valore intero per il campo ageInteger value for age field Fascia di età corrispondenteCorresponding age range
651651 Da 13 a 1713 to 17
652652 Da 18 a 2418 to 24
653653 Da 25 a 3425 to 34
654654 Da 35 a 4935 to 49
655655 Da 50 in su50 and above

Per ottenere i valori supportati per il campo age a livello di codice, è possibile eseguire una chiamata al metodo GET seguente.To get the supported values for the age field programmatically, you can call the following GET method. Per il Authorization intestazione, passare il token di accesso di Azure AD nel formato Bearer < 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>

Il codice di esempio riportato di seguito mostra il corpo della risposta per questo metodo.The following example shows the response body for this method.

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

Valori di sessoGender values

Il campo gender dell'oggetto TargetingProfile contiene uno o più dei seguenti valori interi che identificano i sessi degli utenti da definire come target.The gender field in the TargetingProfile object contains one or more of the following integers that identify the genders of the users to target.

Valore intero per il campo genderInteger value for gender field Sesso corrispondenteCorresponding gender
Procedura di risoluzione per l'ID evento 700700 MaleMale
701701 FemaleFemale

Per ottenere i valori supportati per il campo gender a livello di codice, è possibile eseguire una chiamata al metodo GET seguente.To get the supported values for the gender field programmatically, you can call the following GET method. Per il Authorization intestazione, passare il token di accesso di Azure AD nel formato Bearer < 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>

Il codice di esempio riportato di seguito mostra il corpo della risposta per questo metodo.The following example shows the response body for this method.

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

Valori di versione SOOS version values

Il campo osVersion dell'oggetto TargetingProfile contiene uno o più dei seguenti valori interi che identificano le versioni del sistema operativo degli utenti da definire come target.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.

Valore intero per il campo osVersionInteger value for osVersion field Versione del sistema operativo corrispondenteCorresponding 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

Per ottenere i valori supportati per il campo osVersion a livello di codice, è possibile eseguire una chiamata al metodo GET seguente.To get the supported values for the osVersion field programmatically, you can call the following GET method. Per il Authorization intestazione, passare il token di accesso di Azure AD nel formato Bearer < 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>

Il codice di esempio riportato di seguito mostra il corpo della risposta per questo metodo.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"
    }
  }
}

Valori del tipo di dispositivoDevice type values

Il campo deviceType dell'oggetto TargetingProfile contiene uno o più dei seguenti valori interi che identificano i tipi di dispositivo degli utenti da definire come target.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.

Valore intero per il campo deviceTypeInteger value for deviceType field Tipo di dispositivo corrispondenteCorresponding device type DescrizioneDescription
710710 WindowsWindows Rappresenta i dispositivi che eseguono una versione desktop di Windows 10 o Windows 8.x.This represents devices running a desktop version of Windows 10 or Windows 8.x.
711711 PhonePhone Rappresenta i dispositivi che eseguono Windows 10 Mobile, Windows Phone 8.x o Windows Phone 7.x.This represents devices running Windows 10 Mobile, Windows Phone 8.x, or Windows Phone 7.x.

Per ottenere i valori supportati per il campo deviceType a livello di codice, è possibile eseguire una chiamata al metodo GET seguente.To get the supported values for the deviceType field programmatically, you can call the following GET method. Per il Authorization intestazione, passare il token di accesso di Azure AD nel formato Bearer < 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>

Il codice di esempio riportato di seguito mostra il corpo della risposta per questo metodo.The following example shows the response body for this method.

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

Valori del tipo di approvvigionamentoSupply type values

Il campo supplyType dell'oggetto TargetingProfile contiene uno o più dei seguenti valori interi che identificano il tipo di inventario in cui verranno mostrati gli annunci della campagna.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.

Valore intero per il campo supplyTypeInteger value for supplyType field Tipo di approvvigionamento corrispondenteCorresponding supply type DescrizioneDescription
1147011470 AppApp Si riferisce agli annunci che vengono visualizzati solo nelle app.This refers to ads that appear in apps only.
1147111471 UniversaleUniversal Si riferisce agli annunci che vengono visualizzati nelle app, sul Web e su altre superfici di visualizzazione.This refers to ads that appear in apps, on the Web, and on and other display surfaces.

Per ottenere i valori supportati per il campo supplyType a livello di codice, è possibile eseguire una chiamata al metodo GET seguente.To get the supported values for the supplyType field programmatically, you can call the following GET method. Per il Authorization intestazione, passare il token di accesso di Azure AD nel formato Bearer < 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>

Il codice di esempio riportato di seguito mostra il corpo della risposta per questo metodo.The following example shows the response body for this method.

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

Valori di codice paeseCountry code values

Il campo country dell'oggetto TargetingProfile contiene uno o più dei seguenti valori interi che identificano i codici paese ISO 3166-1 alpha-2 degli utenti da impostare come target.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.

Valore intero per il campo countryInteger value for country field Codice paese corrispondenteCorresponding country code
11 Stati UnitiUS
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 Internet ExplorerIE
1515 ITIT
1616 JPJP
1717 LULU
1818 MXMX
1919 NLNL
2020 NZNZ
2121 NONO
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 RUHR
6060 RUHR
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

Per ottenere i valori supportati per il campo country a livello di codice, è possibile eseguire una chiamata al metodo GET seguente.To get the supported values for the country field programmatically, you can call the following GET method. Per il Authorization intestazione, passare il token di accesso di Azure AD nel formato Bearer < 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>

Il codice di esempio riportato di seguito mostra il corpo della risposta per questo metodo.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"
    }
  }
}