管理目標設定檔

發行項
10/05/2023

在 Microsoft Store 促銷 API 中使用這些方法，以選取您想要針對促銷廣告行銷活動中每個傳遞明細設定目標的使用者、地理位置和庫存類型。您可以跨多個傳遞明細建立及重複使用目標設定檔。

如需目標設定檔與廣告行銷活動、傳遞明細和廣告廣告素材之間關聯性的詳細資訊，請參閱使用 Microsoft Store Services 執行廣告行銷活動。

必要條件

若要使用這些方法，您必須先執行下列動作：

如果您尚未這麼做，請完成 Microsoft Store 促銷 API 的所有必要條件。
取得 Azure AD 存取權杖，以用於這些方法的要求標頭中。取得存取權杖之後，您在其到期之前有 60 分鐘的時間可以使用。權杖到期之後，您可以取得新的權杖。

要求

這些方法具有下列 URI。

方法類型	要求 URI	描述
POST	`https://manage.devcenter.microsoft.com/v1.0/my/promotion/targeting-profile`	建立新的目標設定檔。
PUT	`https://manage.devcenter.microsoft.com/v1.0/my/promotion/targeting-profile/{targetingProfileId}`	編輯 targetingProfileId 所指定的目標設定檔。
取得	`https://manage.devcenter.microsoft.com/v1.0/my/promotion/targeting-profile/{targetingProfileId}`	取得 targetingProfileId 所指定的目標設定檔。

標題	類型	描述
授權	字串	必要。持有人<權杖>形式的Azure AD 存取權杖。
追蹤 ID	GUID	選擇性。追蹤呼叫流程的識別碼。

要求本文

POST 和 PUT 方法需要 JSON 要求本文，其中包含目標設定檔物件的必要欄位，以及您想要設定或變更的任何其他欄位。

要求範例

下列範例示範如何呼叫 POST 方法來建立目標設定檔。

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 方法來擷取目標設定檔。

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

回應

這些方法會傳回 JSON 回應本文，其中的目標設定檔物件包含已建立、更新或擷取目標設定檔的相關資訊。下列範例示範這些方法的回應本文。

{
  "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
    ]
  }
}

目標設定檔物件

這些方法的要求和回應本文包含下欄欄位。下表顯示哪些欄位是唯讀的 (表示無法在 PUT 方法中變更欄位)，以及 POST 方法的要求本文中需要哪些欄位。

欄位	類型	描述	唯讀	預設	POST 的必要項目
識別碼	整數	目標設定檔的識別碼。	是		No
NAME	字串	目標設定檔的名稱。	No		Yes
targetingType	string	下列其中一個值：自動：指定此值以允許 Microsoft 根據合作夥伴中心應用程式的設定來選擇目標設定檔。手動：指定此值以定義您自己的目標設定檔。	No	自動	Yes
年齡	陣列	一或多個整數，可識別要鎖定使用者的年齡範圍。如需整數的完整清單，請參閱本文中的年齡值。	No	null	No
性別	陣列	一或多個整數，可識別要鎖定使用者的性別。如需整數的完整清單，請參閱本文中的性別值。	No	null	No
國家/地區	陣列	一或多個整數，可識別要鎖定使用者的國碼 (地區碼)。如需整數的完整清單，請參閱本文中的國碼 (地區碼) 值。	No	null	No
osVersion	陣列	一或多個整數，可識別要鎖定使用者的 OS 版本。如需整數的完整清單，請參閱本文中的 OS 版本值。	No	null	No
deviceType	陣列	一或多個整數，可識別要鎖定使用者的裝置類型。如需整數的完整清單，請參閱本文中的裝置類型值。	No	null	No
supplyType	陣列	一或多個整數，可識別行銷活動廣告顯示所在的庫存類型。如需整數的完整清單，請參閱本文中的提供類型值。	No	null	No

年齡值

TargetingProfile 物件中的 [年齡] 欄位包含下列一或多個整數，可識別要鎖定使用者的年齡範圍。

[年齡] 欄位的整數值	對應的年齡範圍
651	13 到 17
652	18 到 24
653	25 到 34
654	35 到 49
655	50 和以上

若要以程式設計方式取得 [年齡] 欄位支援的值，您可以呼叫下列 GET 方法。針對 Authorization 標頭，以持有人<權杖>的形式傳遞您的 Azure AD 存取權杖。

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

下面範例會示範回應本文的格式。

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

性別值

TargetingProfile 物件中的 [性別] 欄位包含下列一或多個整數，可識別要鎖定使用者的性別。

[性別] 欄位的整數值	對應的性別
700	男性
701	女性

若要以程式設計方式取得 [性別] 欄位支援的值，您可以呼叫下列 GET 方法。針對 Authorization 標頭，以持有人<權杖>的形式傳遞您的 Azure AD 存取權杖。

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

下面範例會示範回應本文的格式。

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

OS 版本值

TargetingProfile 物件中的 osVersion 欄位包含下列一或多個整數，可識別要鎖定使用者的 OS 版本。

[osVersion] 欄位的整數值	對應的 OS 版本
500	Windows Phone 7
501	Windows Phone 7.1
502	Windows Phone 7.5
503	Windows Phone 7.8
504	Windows Phone 8.0
505	Windows Phone 8.1
506	Windows 8.0
507	Windows 8.1
508	Windows 10
509	Windows 10 Mobile
510	Windows 11

若要以程式設計方式取得 [osVersion] 欄位支援的值，您可以呼叫下列 GET 方法。針對 Authorization 標頭，以持有人<權杖>的形式傳遞您的 Azure AD 存取權杖。

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

下面範例會示範回應本文的格式。

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

裝置類型值

TargetingProfile 物件中的 [deviceType] 欄位包含下列一或多個整數，可識別要鎖定使用者的裝置類型。

[deviceType] 欄位的整數值	對應的裝置類型	描述
710	Windows	這代表執行 Windows 11、Windows 10 或 Windows 8.x 桌面版的裝置。
711	電話	這代表執行 Windows 10 行動裝置版、Windows Phone 8.x 或 Windows Phone 7.x 的裝置。

若要以程式設計方式取得 [deviceType] 欄位支援的值，您可以呼叫下列 GET 方法。針對 Authorization 標頭，以持有人<權杖>的形式傳遞您的 Azure AD 存取權杖。

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

下面範例會示範回應本文的格式。

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

提供類型值

TargetingProfile 物件中的 [supplyType] 欄位包含下列一或多個整數，可識別行銷活動廣告顯示位置的庫存類型。

[supplyType] 欄位的整數值	對應的提供類型	描述
11470	App	這是指僅出現在應用程式中的廣告。
11471	環球	這是指出現在應用程式中、網頁和其他顯示介面上的廣告。

若要以程式設計方式取得 [supplyType] 欄位支援的值，您可以呼叫下列 GET 方法。針對 Authorization 標頭，以持有人<權杖>的形式傳遞您的 Azure AD 存取權杖。

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

下面範例會示範回應本文的格式。

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

國碼 (地區碼) 值

TargetingProfile 物件中的 [國家/地區] 欄位包含下列一或多個整數，可識別要鎖定使用者的 ISO 3166-1 alpha-2 國碼 (地區碼)。

[國家/地區] 欄位的整數值	對應的國碼 (地區碼)
1	美國
2	AU
3	AT
4	BE
5	巴西
6	CA
7	DK
8	FI
9	法國
10	DE
11	GR
12	香港
13	IN
14	IE
15	IT
16	日本
17	LU
18	MX
19	荷蘭
20	紐西蘭
21	否
22	波蘭
23	PT
24	SG
25	ES
26	SE
27	CH
28	台灣
29	GB
30	俄羅斯
31	CL
32	CO
33	捷克
34	匈牙利
35	南非
36	韓國
37	CN
38	RO
39	土耳其
40	SK
41	伊利諾州
42	識別碼
43	AR
44	MY
45	PH
46	PE
47	烏克蘭
48	阿拉伯聯合大公國
49	TH
50	伊拉克
51	VN
52	哥斯大黎加
53	佛蒙特州
54	QA
55	SI
56	BG
57	LT
58	RS
59	HR
60	HR
61	LV
62	EE
63	IS
64	哈薩克
65	SA
67	AL
68	阿爾及利亞
70	AO
72	上午
73	AZ
74	BS
75	孟加拉
76	BB
77	BY
81	BO
82	波士尼亞與赫塞哥維納
83	BW
87	柬埔寨
88	喀麥隆
94	CD
95	CI
96	CY
99	D 0
100	EC
101	埃及
102	薩爾瓦多
107	斐濟
108	GA
110	GE
111	迦納
114	GT
118	HT
119	宏都拉斯
120	牙買加
121	約旦
122	KB
124	KW
125	吉爾吉斯
126	洛杉磯
127	LB
133	北馬其頓
135	MW
138	MT
141	模里西斯
145	ME
146	MA
147	MZ
148	NA
150	NP
151	NI
153	奈及利亞
154	OM
155	PK
157	PA
159	巴拉圭
167	SN
172	斯里蘭卡
176	坦尚尼亞
180	TT
181	TN
184	烏干達
185	烏拉圭
186	烏茲別克
189	尚比亞
190	辛巴威
219	MD
224	PS
225	RE
246	PR

若要以程式設計方式取得 [國家/地區] 欄位的支援值，您可以呼叫下列 GET 方法。針對 Authorization 標頭，以持有人<權杖>的形式傳遞您的 Azure AD 存取權杖。

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

下面範例會示範回應本文的格式。

{
  "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"
    }
  }
}

共用方式為

管理目標設定檔

必要條件

要求

標題

要求本文

要求範例

回應

目標設定檔物件

年齡值

性別值

OS 版本值

裝置類型值

提供類型值

國碼 (地區碼) 值

意見反應

其他資源

共用方式為

管理目標設定檔

必要條件

要求

標題

要求本文

要求範例

回應

目標設定檔物件

年齡值

性別值

OS 版本值

裝置類型值

提供類型值

國碼 (地區碼) 值

相關主題

意見反應

其他資源