GetAuctionInsightData 服務作業 - Ad Insight

發行項
12/21/2023

取得帳戶、活動、廣告群組或關鍵字的深入解析資料。

藉由向您顯示成功之處，以及您可能遺失提升效能的機會，深入解析資料可協助您做出策略性優化決策。

如果這是新的行銷活動，或您印象太少，就不會產生深入解析資料。

資料保留期間為 180 天。

要求專案

GetAuctionInsightDataRequest物件會定義服務作業要求的主體和標頭元素。元素的順序必須與要求 SOAP中所示的順序相同。

注意事項

除非下面另有說明，否則所有要求專案都是必要的。

要求本文專案

元素	說明	資料類型
EntityIds	最多 200 個行銷活動、廣告群組或關鍵字的 Microsoft Advertising 識別碼。行銷活動、廣告群組和關鍵字實體類型需要此元素。如果 EntityType 是 Account，這個元素是選擇性的，而且會覆寫 CustomerAccountId 標頭中設定的值。不論實體類型為何，您都必須設定 CustomerId 和 CustomerAccountId 標頭元素。	long 陣列
EntityType	您想要要求深入解析資料的實體層級。支援的值為 Account、Campaign、AdGroup 和 Keyword。這個元素是必要的。	EntityType
ReturnAdditionalFields	您想要包含在每個傳回的深入解析 KPI 中的其他屬性清單。其他域值可讓您使用目前版本的 Ad Insight API 取得最新功能，而在下一個版本中，預設會包含對應的元素。此要求專案是選擇性的。	應徵者InsightKpiAdditionalField
SearchParameters	搜尋參數會定義您的準則，並篩選出深入解析資料。您必須只包含一個 DateRangeSearchParameter。此外，您可以選擇性地包含最多三個不同的一般SegmentSearchParameter 物件，例如 Day、DayOfWeek 和 Device。衍生自 SearchParameter 的其他物件對此作業無效。	SearchParameter 數組

要求標頭元素

元素	說明	資料類型
AuthenticationToken	OAuth 存取權杖，代表具有 Microsoft Advertising 帳戶許可權之使用者的認證。如需詳細資訊，請參閱使用 OAuth 進行驗證。	string
CustomerAccountId	擁有或與要求中實體相關聯之廣告帳戶的識別碼。當兩者都需要時，此標頭元素必須具有與 AccountId body 元素相同的值。此元素是大部分服務作業的必要專案，最佳做法是一律加以設定。如需詳細資訊，請參閱取得您的帳戶和客戶識別碼。	string
CustomerId	(使用者存取或操作之使用者) 客戶的管理員帳戶識別碼。使用者可以存取多個管理員帳戶。此元素是大部分服務作業的必要專案，最佳做法是一律加以設定。如需詳細資訊，請參閱取得您的帳戶和客戶識別碼。	string
DeveloperToken	用來存取 Bing 廣告 API 的開發人員權杖。如需詳細資訊，請參閱取得開發人員權杖。	string
密碼	此元素會保留供內部使用，並會從未來的 API 版本中移除。您必須使用 AuthenticationToken 元素來設定使用者認證。	string
UserName	此元素會保留供內部使用，並會從未來的 API 版本中移除。您必須使用 AuthenticationToken 元素來設定使用者認證。	string

Response 元素

GetAuctionInsightDataResponse物件會定義服務作業回應的主體和標頭元素。這些元素的傳回順序與回應 SOAP中所示的順序相同。

回應本文專案

元素	說明	資料類型
結果	包含所要求實體、日期範圍和區段搜尋參數的深入解析專案。	品品InsightResult

回應標頭元素

元素	說明	資料類型
TrackingId	包含 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/AdInsight/v13">
    <Action mustUnderstand="1">GetAuctionInsightData</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>
    <GetAuctionInsightDataRequest xmlns="https://bingads.microsoft.com/AdInsight/v13">
      <EntityType>ValueHere</EntityType>
      <EntityIds i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:long>ValueHere</a1:long>
      </EntityIds>
      <SearchParameters i:nil="false">
        <SearchParameter i:type="-- derived type specified here with the appropriate prefix --">
          <!--These fields are applicable if the derived type attribute is set to DateRangeSearchParameter-->
          <EndDate i:nil="false">
            <Day>ValueHere</Day>
            <Month>ValueHere</Month>
            <Year>ValueHere</Year>
          </EndDate>
          <StartDate i:nil="false">
            <Day>ValueHere</Day>
            <Month>ValueHere</Month>
            <Year>ValueHere</Year>
          </StartDate>
          <!--This field is applicable if the derived type attribute is set to AuctionSegmentSearchParameter-->
          <Segment>ValueHere</Segment>
        </SearchParameter>
      </SearchParameters>
      <ReturnAdditionalFields i:nil="false">ValueHere</ReturnAdditionalFields>
    </GetAuctionInsightDataRequest>
  </s:Body>
</s:Envelope>

回應 SOAP

此範本是由工具所產生，用來顯示 SOAP 回應的主體和標頭元素順序。

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Header xmlns="https://bingads.microsoft.com/AdInsight/v13">
    <TrackingId d3p1:nil="false" xmlns:d3p1="http://www.w3.org/2001/XMLSchema-instance">ValueHere</TrackingId>
  </s:Header>
  <s:Body>
    <GetAuctionInsightDataResponse xmlns="https://bingads.microsoft.com/AdInsight/v13">
      <Result d4p1:nil="false" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
        <Segments d4p1:nil="false">
          <AuctionSegment>ValueHere</AuctionSegment>
        </Segments>
        <Entries d4p1:nil="false">
          <AuctionInsightEntry>
            <DisplayDomain d4p1:nil="false">ValueHere</DisplayDomain>
            <AggregatedKpi d4p1:nil="false">
              <Segments d4p1:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
                <a1:string>ValueHere</a1:string>
              </Segments>
              <ImpressionShare>ValueHere</ImpressionShare>
              <OverlapRate>ValueHere</OverlapRate>
              <AveragePosition>ValueHere</AveragePosition>
              <AboveRate>ValueHere</AboveRate>
              <TopOfPageRate>ValueHere</TopOfPageRate>
              <OutrankingShare>ValueHere</OutrankingShare>
              <AbsoluteTopOfPageRate>ValueHere</AbsoluteTopOfPageRate>
            </AggregatedKpi>
            <SegmentedKpis d4p1:nil="false">
              <AuctionInsightKpi>
                <Segments d4p1:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
                  <a1:string>ValueHere</a1:string>
                </Segments>
                <ImpressionShare>ValueHere</ImpressionShare>
                <OverlapRate>ValueHere</OverlapRate>
                <AveragePosition>ValueHere</AveragePosition>
                <AboveRate>ValueHere</AboveRate>
                <TopOfPageRate>ValueHere</TopOfPageRate>
                <OutrankingShare>ValueHere</OutrankingShare>
                <AbsoluteTopOfPageRate>ValueHere</AbsoluteTopOfPageRate>
              </AuctionInsightKpi>
            </SegmentedKpis>
          </AuctionInsightEntry>
        </Entries>
        <UsedImpressions>ValueHere</UsedImpressions>
        <UsedKeywords>ValueHere</UsedKeywords>
      </Result>
    </GetAuctionInsightDataResponse>
  </s:Body>
</s:Envelope>

程式碼語法

範例語法可以與 Bing 廣告 SDK搭配使用。如需更多範例，請參閱 Bing 廣告 API 程式碼范例。

public async Task<GetAuctionInsightDataResponse> GetAuctionInsightDataAsync(
	EntityType entityType,
	IList<long> entityIds,
	IList<SearchParameter> searchParameters,
	AuctionInsightKpiAdditionalField? returnAdditionalFields)
{
	var request = new GetAuctionInsightDataRequest
	{
		EntityType = entityType,
		EntityIds = entityIds,
		SearchParameters = searchParameters,
		ReturnAdditionalFields = returnAdditionalFields
	};

	return (await AdInsightService.CallAsync((s, r) => s.GetAuctionInsightDataAsync(r), request));
}

static GetAuctionInsightDataResponse getAuctionInsightData(
	EntityType entityType,
	ArrayOflong entityIds,
	ArrayOfSearchParameter searchParameters,
	ArrayList<AuctionInsightKpiAdditionalField> returnAdditionalFields) throws RemoteException, Exception
{
	GetAuctionInsightDataRequest request = new GetAuctionInsightDataRequest();

	request.setEntityType(entityType);
	request.setEntityIds(entityIds);
	request.setSearchParameters(searchParameters);
	request.setReturnAdditionalFields(returnAdditionalFields);

	return AdInsightService.getService().getAuctionInsightData(request);
}

static function GetAuctionInsightData(
	$entityType,
	$entityIds,
	$searchParameters,
	$returnAdditionalFields)
{

	$GLOBALS['Proxy'] = $GLOBALS['AdInsightProxy'];

	$request = new GetAuctionInsightDataRequest();

	$request->EntityType = $entityType;
	$request->EntityIds = $entityIds;
	$request->SearchParameters = $searchParameters;
	$request->ReturnAdditionalFields = $returnAdditionalFields;

	return $GLOBALS['AdInsightProxy']->GetService()->GetAuctionInsightData($request);
}

response=adinsight_service.GetAuctionInsightData(
	EntityType=EntityType,
	EntityIds=EntityIds,
	SearchParameters=SearchParameters,
	ReturnAdditionalFields=ReturnAdditionalFields)

需求

服務： AdInsightService.svc v13
命名空間： https://bingads.microsoft.com/AdInsight/v13

共用方式為