GetAudiencesByIds 服务操作 - 市场活动管理
从指定帐户检索指定的访问群体。
请求元素
GetAudiencesByIdsRequest 对象定义服务操作请求的正文和标头元素。 元素的顺序必须与 请求 SOAP 中所示的顺序相同。
注意
除非下面另有说明,否则需要所有请求元素。
请求正文元素
元素 | 说明 | 数据类型 |
---|---|---|
AudienceIds | 最多 100 个所请求访问群体的标识符。 此请求元素是可选的。 如果此元素为 null 或空,则有效请求指定帐户的所有客户和帐户范围受众。 如果访问群体标识符与请求的访问群体类型不匹配,则该操作将为每个请求的访问群体 ID 返回批处理错误。 |
long 数组 |
ReturnAdditionalFields | 借助其他字段值,可以使用当前版本的市场活动管理 API 获取最新功能,并在下一个版本中默认包含相应的元素。 此请求元素是可选的。 |
AudienceAdditionalField |
类型 | 要返回的受众类型。 可以包含多个值作为标志。 如何指定多个标志取决于所使用的编程语言。 例如,C# 将这些值视为标志值,Java 将它们视为字符串数组。 SOAP 应包含一个字符串,其中包含以空格分隔的值列表, <Type>RemarketingList SimilarRemarketingList</Type> 例如 。 |
AudienceType |
请求标头元素
元素 | 说明 | 数据类型 |
---|---|---|
AuthenticationToken | OAuth 访问令牌,表示有权Microsoft广告帐户的用户的凭据。 有关详细信息,请参阅 使用 OAuth 进行身份验证。 |
string |
CustomerAccountId | 拥有或与请求中的实体关联的广告帐户的标识符。 如果需要这两个元素,此标头元素必须与 AccountId 正文元素具有相同的值。 此元素是大多数服务操作所必需的,作为最佳做法,应始终设置它。 有关详细信息,请参阅 获取帐户和客户 ID。 |
string |
CustomerId | 用户正在访问或操作的客户) 经理帐户 (标识符。 用户可以访问多个经理帐户。 此元素是大多数服务操作所必需的,作为最佳做法,应始终设置它。 有关详细信息,请参阅 获取帐户和客户 ID。 |
string |
DeveloperToken | 用于访问必应广告 API 的开发人员令牌。 有关详细信息,请参阅 获取开发人员令牌。 |
string |
Password | 此元素保留供内部使用,将从 API 的未来版本中删除。 必须使用 AuthenticationToken 元素来设置用户凭据。 | string |
UserName | 此元素保留供内部使用,将从 API 的未来版本中删除。 必须使用 AuthenticationToken 元素来设置用户凭据。 | string |
响应元素
GetAudiencesByIdsResponse 对象定义服务操作响应的正文和标头元素。 元素的返回顺序与 响应 SOAP 中所示的顺序相同。
响应正文元素
元素 | 说明 | 数据类型 |
---|---|---|
访问群体 | 与请求中指定的访问群体标识符直接对应的访问群体列表。 列表的项可能返回为 null。 对于未检索访问群体的每个列表索引,相应的元素将为 null。 | 受众 数组 |
PartialErrors |
BatchError 对象的数组,其中包含未成功的任何请求项的详细信息。 错误列表与请求中的项列表不直接对应。 如果没有错误,列表可以为空,也可以包含与请求中每个不成功的列表项对应的一个或多个错误对象。 |
BatchError 数组 |
响应标头元素
元素 | 说明 | 数据类型 |
---|---|---|
跟踪 ID | 包含 API 调用详细信息的日志条目的标识符。 | string |
请求 SOAP
此模板由一个工具生成,用于显示 SOAP 请求的正文和标头元素的顺序。 有关可用于此服务操作的支持类型,请参阅上面的 请求正文元素 参考。
<s:Envelope xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
<Action mustUnderstand="1">GetAudiencesByIds</Action>
<AuthenticationToken i:nil="false">ValueHere</AuthenticationToken>
<CustomerAccountId i:nil="false">ValueHere</CustomerAccountId>
<CustomerId i:nil="false">ValueHere</CustomerId>
<DeveloperToken i:nil="false">ValueHere</DeveloperToken>
</s:Header>
<s:Body>
<GetAudiencesByIdsRequest xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
<AudienceIds i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<a1:long>ValueHere</a1:long>
</AudienceIds>
<Type>ValueHere</Type>
<ReturnAdditionalFields i:nil="false">ValueHere</ReturnAdditionalFields>
</GetAudiencesByIdsRequest>
</s:Body>
</s:Envelope>
响应 SOAP
此模板由一个工具生成,用于显示 SOAP 响应的 正文 和 标头 元素的顺序。
<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
<s:Header xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
<TrackingId d3p1:nil="false" xmlns:d3p1="http://www.w3.org/2001/XMLSchema-instance">ValueHere</TrackingId>
</s:Header>
<s:Body>
<GetAudiencesByIdsResponse xmlns="https://bingads.microsoft.com/CampaignManagement/v13">
<Audiences d4p1:nil="false" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
<Audience d4p1:type="-- derived type specified here with the appropriate prefix --">
<AudienceNetworkSize d4p1:nil="false">ValueHere</AudienceNetworkSize>
<CustomerShare d4p1:nil="false">
<CustomerAccountShares d4p1:nil="false">
<CustomerAccountShare>
<AccountId d4p1:nil="false">ValueHere</AccountId>
<Associations d4p1:nil="false">
<CustomerAccountShareAssociation>
<AssociationCount d4p1:nil="false">ValueHere</AssociationCount>
<UsageType d4p1:nil="false">ValueHere</UsageType>
</CustomerAccountShareAssociation>
</Associations>
<CustomerId d4p1:nil="false">ValueHere</CustomerId>
</CustomerAccountShare>
</CustomerAccountShares>
<OwnerCustomerId d4p1:nil="false">ValueHere</OwnerCustomerId>
</CustomerShare>
<Description d4p1:nil="false">ValueHere</Description>
<ForwardCompatibilityMap xmlns:e411="http://schemas.datacontract.org/2004/07/System.Collections.Generic" d4p1:nil="false">
<e411:KeyValuePairOfstringstring>
<e411:key d4p1:nil="false">ValueHere</e411:key>
<e411:value d4p1:nil="false">ValueHere</e411:value>
</e411:KeyValuePairOfstringstring>
</ForwardCompatibilityMap>
<Id d4p1:nil="false">ValueHere</Id>
<MembershipDuration d4p1:nil="false">ValueHere</MembershipDuration>
<Name d4p1:nil="false">ValueHere</Name>
<ParentId d4p1:nil="false">ValueHere</ParentId>
<Scope d4p1:nil="false">ValueHere</Scope>
<SearchSize d4p1:nil="false">ValueHere</SearchSize>
<SupportedCampaignTypes d4p1:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<a1:string>ValueHere</a1:string>
</SupportedCampaignTypes>
<Type>ValueHere</Type>
<!--These fields are applicable if the derived type attribute is set to RemarketingList-->
<Rule d4p1:nil="false" d4p1:type="-- derived type specified here with the appropriate prefix --">
<Type d4p1:nil="false">ValueHere</Type>
<!--These fields are applicable if the derived type attribute is set to PageVisitorsRule-->
<NormalForm d4p1:nil="false">ValueHere</NormalForm>
<RuleItemGroups d4p1:nil="false">
<RuleItemGroup>
<Items d4p1:nil="false">
<RuleItem d4p1:type="-- derived type specified here with the appropriate prefix --">
<Type d4p1:nil="false">ValueHere</Type>
<!--These fields are applicable if the derived type attribute is set to StringRuleItem-->
<Operand d4p1:nil="false">ValueHere</Operand>
<Operator>ValueHere</Operator>
<Value d4p1:nil="false">ValueHere</Value>
<!--These fields are applicable if the derived type attribute is set to NumberRuleItem-->
<Operand d4p1:nil="false">ValueHere</Operand>
<Operator>ValueHere</Operator>
<Value d4p1:nil="false">ValueHere</Value>
</RuleItem>
</Items>
</RuleItemGroup>
</RuleItemGroups>
<!--These fields are applicable if the derived type attribute is set to PageVisitorsWhoVisitedAnotherPageRule-->
<AnotherRuleItemGroups d4p1:nil="false">
<RuleItemGroup>
<Items d4p1:nil="false">
<RuleItem d4p1:type="-- derived type specified here with the appropriate prefix --">
<Type d4p1:nil="false">ValueHere</Type>
<!--These fields are applicable if the derived type attribute is set to StringRuleItem-->
<Operand d4p1:nil="false">ValueHere</Operand>
<Operator>ValueHere</Operator>
<Value d4p1:nil="false">ValueHere</Value>
<!--These fields are applicable if the derived type attribute is set to NumberRuleItem-->
<Operand d4p1:nil="false">ValueHere</Operand>
<Operator>ValueHere</Operator>
<Value d4p1:nil="false">ValueHere</Value>
</RuleItem>
</Items>
</RuleItemGroup>
</AnotherRuleItemGroups>
<RuleItemGroups d4p1:nil="false">
<RuleItemGroup>
<Items d4p1:nil="false">
<RuleItem d4p1:type="-- derived type specified here with the appropriate prefix --">
<Type d4p1:nil="false">ValueHere</Type>
<!--These fields are applicable if the derived type attribute is set to StringRuleItem-->
<Operand d4p1:nil="false">ValueHere</Operand>
<Operator>ValueHere</Operator>
<Value d4p1:nil="false">ValueHere</Value>
<!--These fields are applicable if the derived type attribute is set to NumberRuleItem-->
<Operand d4p1:nil="false">ValueHere</Operand>
<Operator>ValueHere</Operator>
<Value d4p1:nil="false">ValueHere</Value>
</RuleItem>
</Items>
</RuleItemGroup>
</RuleItemGroups>
<!--These fields are applicable if the derived type attribute is set to PageVisitorsWhoDidNotVisitAnotherPageRule-->
<ExcludeRuleItemGroups d4p1:nil="false">
<RuleItemGroup>
<Items d4p1:nil="false">
<RuleItem d4p1:type="-- derived type specified here with the appropriate prefix --">
<Type d4p1:nil="false">ValueHere</Type>
<!--These fields are applicable if the derived type attribute is set to StringRuleItem-->
<Operand d4p1:nil="false">ValueHere</Operand>
<Operator>ValueHere</Operator>
<Value d4p1:nil="false">ValueHere</Value>
<!--These fields are applicable if the derived type attribute is set to NumberRuleItem-->
<Operand d4p1:nil="false">ValueHere</Operand>
<Operator>ValueHere</Operator>
<Value d4p1:nil="false">ValueHere</Value>
</RuleItem>
</Items>
</RuleItemGroup>
</ExcludeRuleItemGroups>
<IncludeRuleItemGroups d4p1:nil="false">
<RuleItemGroup>
<Items d4p1:nil="false">
<RuleItem d4p1:type="-- derived type specified here with the appropriate prefix --">
<Type d4p1:nil="false">ValueHere</Type>
<!--These fields are applicable if the derived type attribute is set to StringRuleItem-->
<Operand d4p1:nil="false">ValueHere</Operand>
<Operator>ValueHere</Operator>
<Value d4p1:nil="false">ValueHere</Value>
<!--These fields are applicable if the derived type attribute is set to NumberRuleItem-->
<Operand d4p1:nil="false">ValueHere</Operand>
<Operator>ValueHere</Operator>
<Value d4p1:nil="false">ValueHere</Value>
</RuleItem>
</Items>
</RuleItemGroup>
</IncludeRuleItemGroups>
<!--These fields are applicable if the derived type attribute is set to CustomEventsRule-->
<Action d4p1:nil="false">ValueHere</Action>
<ActionOperator>ValueHere</ActionOperator>
<Category d4p1:nil="false">ValueHere</Category>
<CategoryOperator>ValueHere</CategoryOperator>
<Label d4p1:nil="false">ValueHere</Label>
<LabelOperator>ValueHere</LabelOperator>
<Value d4p1:nil="false">ValueHere</Value>
<ValueOperator>ValueHere</ValueOperator>
</Rule>
<TagId d4p1:nil="false">ValueHere</TagId>
<!--No additional fields are applicable if the derived type attribute is set to CustomAudience-->
<!--No additional fields are applicable if the derived type attribute is set to InMarketAudience-->
<!--These fields are applicable if the derived type attribute is set to ProductAudience-->
<ProductAudienceType d4p1:nil="false">ValueHere</ProductAudienceType>
<TagId d4p1:nil="false">ValueHere</TagId>
<!--This field is applicable if the derived type attribute is set to SimilarRemarketingList-->
<SourceId>ValueHere</SourceId>
<!--This field is applicable if the derived type attribute is set to CombinedList-->
<CombinationRules d4p1:nil="false">
<CombinationRule>
<AudienceIds d4p1:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
<a1:long>ValueHere</a1:long>
</AudienceIds>
<Operator>ValueHere</Operator>
</CombinationRule>
</CombinationRules>
<!--No additional fields are applicable if the derived type attribute is set to CustomerList-->
<!--These fields are applicable if the derived type attribute is set to ImpressionBasedRemarketingList-->
<AdGroupId d4p1:nil="false">ValueHere</AdGroupId>
<CampaignId d4p1:nil="false">ValueHere</CampaignId>
<EntityType>ValueHere</EntityType>
</Audience>
</Audiences>
<PartialErrors d4p1:nil="false" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
<BatchError d4p1:type="-- derived type specified here with the appropriate prefix --">
<Code>ValueHere</Code>
<Details d4p1:nil="false">ValueHere</Details>
<ErrorCode d4p1:nil="false">ValueHere</ErrorCode>
<FieldPath d4p1:nil="false">ValueHere</FieldPath>
<ForwardCompatibilityMap xmlns:e412="http://schemas.datacontract.org/2004/07/System.Collections.Generic" d4p1:nil="false">
<e412:KeyValuePairOfstringstring>
<e412:key d4p1:nil="false">ValueHere</e412:key>
<e412:value d4p1:nil="false">ValueHere</e412:value>
</e412:KeyValuePairOfstringstring>
</ForwardCompatibilityMap>
<Index>ValueHere</Index>
<Message d4p1:nil="false">ValueHere</Message>
<Type d4p1:nil="false">ValueHere</Type>
<!--These fields are applicable if the derived type attribute is set to EditorialError-->
<Appealable d4p1:nil="false">ValueHere</Appealable>
<DisapprovedText d4p1:nil="false">ValueHere</DisapprovedText>
<Location d4p1:nil="false">ValueHere</Location>
<PublisherCountry d4p1:nil="false">ValueHere</PublisherCountry>
<ReasonCode>ValueHere</ReasonCode>
</BatchError>
</PartialErrors>
</GetAudiencesByIdsResponse>
</s:Body>
</s:Envelope>
代码语法
示例语法可用于 必应广告 SDK。 有关更多示例,请参阅 必应广告 API 代码示例 。
public async Task<GetAudiencesByIdsResponse> GetAudiencesByIdsAsync(
IList<long> audienceIds,
AudienceType type,
AudienceAdditionalField? returnAdditionalFields)
{
var request = new GetAudiencesByIdsRequest
{
AudienceIds = audienceIds,
Type = type,
ReturnAdditionalFields = returnAdditionalFields
};
return (await CampaignManagementService.CallAsync((s, r) => s.GetAudiencesByIdsAsync(r), request));
}
static GetAudiencesByIdsResponse getAudiencesByIds(
ArrayOflong audienceIds,
ArrayList<AudienceType> type,
ArrayList<AudienceAdditionalField> returnAdditionalFields) throws RemoteException, Exception
{
GetAudiencesByIdsRequest request = new GetAudiencesByIdsRequest();
request.setAudienceIds(audienceIds);
request.setType(type);
request.setReturnAdditionalFields(returnAdditionalFields);
return CampaignManagementService.getService().getAudiencesByIds(request);
}
static function GetAudiencesByIds(
$audienceIds,
$type,
$returnAdditionalFields)
{
$GLOBALS['Proxy'] = $GLOBALS['CampaignManagementProxy'];
$request = new GetAudiencesByIdsRequest();
$request->AudienceIds = $audienceIds;
$request->Type = $type;
$request->ReturnAdditionalFields = $returnAdditionalFields;
return $GLOBALS['CampaignManagementProxy']->GetService()->GetAudiencesByIds($request);
}
response=campaignmanagement_service.GetAudiencesByIds(
AudienceIds=AudienceIds,
Type=Type,
ReturnAdditionalFields=ReturnAdditionalFields)
要求
服务: CampaignManagementService.svc v13
命名空间: https://bingads.microsoft.com/CampaignManagement/v13
请求 URL
https://campaign.api.bingads.microsoft.com/CampaignManagement/v13/Audiences/QueryByIds
请求元素
GetAudiencesByIdsRequest 对象定义服务操作请求的正文和标头元素。
注意
除非下面另有说明,否则需要所有请求元素。
请求正文元素
元素 | 说明 | 数据类型 |
---|---|---|
AudienceIds | 最多 100 个所请求访问群体的标识符。 此请求元素是可选的。 如果此元素为 null 或空,则有效请求指定帐户的所有客户和帐户范围受众。 如果访问群体标识符与请求的访问群体类型不匹配,则该操作将为每个请求的访问群体 ID 返回批处理错误。 |
long 数组 |
ReturnAdditionalFields | 借助其他字段值,可以使用当前版本的市场活动管理 API 获取最新功能,并在下一个版本中默认包含相应的元素。 此请求元素是可选的。 |
AudienceAdditionalField |
类型 | 要返回的受众类型。 可以包含多个值作为标志。 如何指定多个标志取决于所使用的编程语言。 例如,C# 将这些值视为标志值,Java 将它们视为字符串数组。 SOAP 应包含一个字符串,其中包含以空格分隔的值列表, <Type>RemarketingList SimilarRemarketingList</Type> 例如 。 |
AudienceType |
请求标头元素
元素 | 说明 | 数据类型 |
---|---|---|
Authorization | OAuth 访问令牌,表示有权Microsoft广告帐户的用户的凭据。 请确保令牌的前缀为“持有者”,这是正确身份验证所必需的。 有关详细信息,请参阅 使用 OAuth 进行身份验证。 |
string |
CustomerAccountId | 拥有或与请求中的实体关联的广告帐户的标识符。 如果需要这两个元素,此标头元素必须与 AccountId 正文元素具有相同的值。 此元素是大多数服务操作所必需的,作为最佳做法,应始终设置它。 有关详细信息,请参阅 获取帐户和客户 ID。 |
string |
CustomerId | 用户正在访问或操作的客户) 经理帐户 (标识符。 用户可以访问多个经理帐户。 此元素是大多数服务操作所必需的,作为最佳做法,应始终设置它。 有关详细信息,请参阅 获取帐户和客户 ID。 |
string |
DeveloperToken | 用于访问必应广告 API 的开发人员令牌。 有关详细信息,请参阅 获取开发人员令牌。 |
string |
Password | 此元素保留供内部使用,将从 API 的未来版本中删除。 必须使用 AuthenticationToken 元素来设置用户凭据。 | string |
UserName | 此元素保留供内部使用,将从 API 的未来版本中删除。 必须使用 AuthenticationToken 元素来设置用户凭据。 | string |
响应元素
GetAudiencesByIdsResponse 对象定义服务操作响应的正文和标头元素。 元素的返回顺序与 响应 JSON 中所示的顺序相同。
响应正文元素
元素 | 说明 | 数据类型 |
---|---|---|
访问群体 | 与请求中指定的访问群体标识符直接对应的访问群体列表。 列表的项可能返回为 null。 对于未检索访问群体的每个列表索引,相应的元素将为 null。 | 受众 数组 |
PartialErrors |
BatchError 对象的数组,其中包含未成功的任何请求项的详细信息。 错误列表与请求中的项列表不直接对应。 如果没有错误,列表可以为空,也可以包含与请求中每个不成功的列表项对应的一个或多个错误对象。 |
BatchError 数组 |
响应标头元素
元素 | 说明 | 数据类型 |
---|---|---|
跟踪 ID | 包含 API 调用详细信息的日志条目的标识符。 | string |
请求 JSON
此模板由显示 JSON 请求的 正文 和 标头 元素的工具生成。 有关可用于此服务操作的支持类型,请参阅上面的 请求正文元素 参考。
{
"AudienceIds": [
"LongValueHere"
],
"Type": "ValueHere",
"ReturnAdditionalFields": "ValueHere"
}
响应 JSON
此模板由一个工具生成,用于显示 JSON 响应的 正文 和 标头 元素。
下面是一个示例,如果 Audience 的类型为 CombinedList,BatchError 为 EditorialError,则适用。
{
"Audiences": [
{
"AudienceNetworkSize": "LongValueHere",
"CustomerShare": {
"CustomerAccountShares": [
{
"AccountId": "LongValueHere",
"Associations": [
{
"AssociationCount": "LongValueHere",
"UsageType": "ValueHere"
}
],
"CustomerId": "LongValueHere"
}
],
"OwnerCustomerId": "LongValueHere"
},
"Description": "ValueHere",
"ForwardCompatibilityMap": [
{
"key": "ValueHere",
"value": "ValueHere"
}
],
"Id": "LongValueHere",
"MembershipDuration": IntValueHere,
"Name": "ValueHere",
"ParentId": "LongValueHere",
"Scope": "ValueHere",
"SearchSize": "LongValueHere",
"SupportedCampaignTypes": [
"ValueHere"
],
"Type": "CombinedList",
"CombinationRules": [
{
"AudienceIds": [
"LongValueHere"
],
"Operator": "ValueHere"
}
]
}
],
"PartialErrors": [
{
"Code": IntValueHere,
"Details": "ValueHere",
"ErrorCode": "ValueHere",
"FieldPath": "ValueHere",
"ForwardCompatibilityMap": [
{
"key": "ValueHere",
"value": "ValueHere"
}
],
"Index": IntValueHere,
"Message": "ValueHere",
"Type": "EditorialError",
"Appealable": "ValueHere",
"DisapprovedText": "ValueHere",
"Location": "ValueHere",
"PublisherCountry": "ValueHere",
"ReasonCode": IntValueHere
}
]
}
代码语法
若要通过 SDK 调用 REST API,需要将 SDK 升级到特定版本并配置系统参数。示例语法可用于 必应广告 SDK。 有关更多示例,请参阅 必应广告 API 代码示例 。
public async Task<GetAudiencesByIdsResponse> GetAudiencesByIdsAsync(
IList<long> audienceIds,
AudienceType type,
AudienceAdditionalField? returnAdditionalFields)
{
var request = new GetAudiencesByIdsRequest
{
AudienceIds = audienceIds,
Type = type,
ReturnAdditionalFields = returnAdditionalFields
};
return (await CampaignManagementService.CallAsync((s, r) => s.GetAudiencesByIdsAsync(r), request));
}
static GetAudiencesByIdsResponse getAudiencesByIds(
ArrayOflong audienceIds,
ArrayList<AudienceType> type,
ArrayList<AudienceAdditionalField> returnAdditionalFields) throws RemoteException, Exception
{
GetAudiencesByIdsRequest request = new GetAudiencesByIdsRequest();
request.setAudienceIds(audienceIds);
request.setType(type);
request.setReturnAdditionalFields(returnAdditionalFields);
return CampaignManagementService.getService().getAudiencesByIds(request);
}
static function GetAudiencesByIds(
$audienceIds,
$type,
$returnAdditionalFields)
{
$GLOBALS['Proxy'] = $GLOBALS['CampaignManagementProxy'];
$request = new GetAudiencesByIdsRequest();
$request->AudienceIds = $audienceIds;
$request->Type = $type;
$request->ReturnAdditionalFields = $returnAdditionalFields;
return $GLOBALS['CampaignManagementProxy']->GetService()->GetAudiencesByIds($request);
}
response=campaignmanagement_service.GetAudiencesByIds(
AudienceIds=AudienceIds,
Type=Type,
ReturnAdditionalFields=ReturnAdditionalFields)