GetHistoricalKeywordPerformance 服務作業 - Ad Insight

發行項
12/21/2023

取得標準化搜尋字詞的歷史效能。結果會依裝置類型匯總。

要求專案

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

注意事項

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

要求本文專案

元素	說明	資料類型
設備	下列一或多個裝置類型的清單：電腦、NonSmartphone、智慧型手機、平板電腦。預設值為 [電腦]。回應會針對您僅在可用時指定的裝置類型，包含關鍵字效能資料。用來判斷指定裝置類型的關鍵字效能。	字串數組
關鍵字	要取得歷史效能統計資料的關鍵字陣列。陣列最多可以包含 1,000 個關鍵字，而且每個關鍵字最多可以包含 100 個字元。	字串數組
語言	用來撰寫關鍵字的語言。您在 PublisherCountries 元素中指定的國家/地區必須支援指定的語言。可能的值包括丹麥文、荷蘭文、英文、芬蘭文、法文、德文、義大利文、挪威文、葡萄牙文、西班牙文、瑞典文和繁體中文。	string
MatchTypes	您想要取得歷程記錄資料的比對類型。您不能指定內容比對類型。	MatchType 數組
PublisherCountries	要作為歷史資料來源之國家/地區的國家/地區代碼。您可以指定一或多個國家/地區代碼。您指定的每個國家/地區都必須支援 Language 元素中指定的語言。支援下列語言和國家/地區組合：丹麥文：DK 荷蘭文：NL 英文：AU、CA、GB、ID、IN、MY、PH、SG、TH、US、VN 芬蘭文：FI 法文：CA、FR 德文：AT、CH、DE 義大利文：IT 挪威文：NB 葡萄牙文：BR 西班牙文：AR、CL、CO、ES、MX、PE、VE 瑞典文：SE TraditionalChinese：HK、TW 如果此元素為 Null，則根據預設，服務會包含支援指定語言的所有國家/地區。	字串數組
TargetAdPosition	您想要取得效能資料的搜尋結果位置。例如，若要使用關鍵字和比對類型，在廣告出現在主線的第一個位置時取得效能資料，請將此元素設定為 MainLine1。若要使用關鍵字和比對類型，在廣告出現在搜尋結果的任何位置時取得效能資料，請將此元素設定為 All。 SixMonths 如果您為此元素指定 All ，服務會針對每個支援的廣告位置，針對每個關鍵字傳回多個結果。如果您指定 Aggregate，服務會傳回一個匯總結果。提要欄位廣告不再提供于美國中 Bing 擁有和營運的網站上。如果您只要求第一頁數據，例如美國) 美國 (FirstPage1，則結果中的KeywordKPI元素會是 nil/empty。如果您在相同的要求中包含其他國家/地區，例如美國和 CA，則任何第一頁結果只會歸屬於美國以外的國家/地區。	AdPosition
TimeInterval	識別用來判斷指定關鍵字之關鍵字之關鍵效能索引之資料的時間週期。例如，使用過去七天或前 30 天的資料來判斷關鍵字效能。預設值為 LastDay。	TimeInterval

要求標頭元素

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

Response 元素

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

回應本文專案

元素	說明	資料類型
KeywordHistoricalPerformances	KeywordHistoricalPerformance資料物件的陣列。陣列包含要求中指定之每個關鍵字、裝置、比對類型和廣告位置的專案。如果關鍵字無效或沒有可用的資料，陣列中的對應專案將會是 Null。	KeywordHistoricalPerformance 數組

回應標頭元素

元素	說明	資料類型
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">GetHistoricalKeywordPerformance</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>
    <GetHistoricalKeywordPerformanceRequest xmlns="https://bingads.microsoft.com/AdInsight/v13">
      <Keywords i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:string>ValueHere</a1:string>
      </Keywords>
      <TimeInterval i:nil="false">ValueHere</TimeInterval>
      <TargetAdPosition i:nil="false">ValueHere</TargetAdPosition>
      <MatchTypes i:nil="false">
        <MatchType>ValueHere</MatchType>
      </MatchTypes>
      <Language i:nil="false">ValueHere</Language>
      <PublisherCountries i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:string>ValueHere</a1:string>
      </PublisherCountries>
      <Devices i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:string>ValueHere</a1:string>
      </Devices>
    </GetHistoricalKeywordPerformanceRequest>
  </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>
    <GetHistoricalKeywordPerformanceResponse xmlns="https://bingads.microsoft.com/AdInsight/v13">
      <KeywordHistoricalPerformances d4p1:nil="false" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
        <KeywordHistoricalPerformance>
          <Keyword d4p1:nil="false">ValueHere</Keyword>
          <KeywordKPIs d4p1:nil="false">
            <KeywordKPI>
              <Device d4p1:nil="false">ValueHere</Device>
              <MatchType>ValueHere</MatchType>
              <AdPosition>ValueHere</AdPosition>
              <Clicks>ValueHere</Clicks>
              <Impressions>ValueHere</Impressions>
              <AverageCPC>ValueHere</AverageCPC>
              <CTR>ValueHere</CTR>
              <TotalCost>ValueHere</TotalCost>
              <AverageBid>ValueHere</AverageBid>
            </KeywordKPI>
          </KeywordKPIs>
        </KeywordHistoricalPerformance>
      </KeywordHistoricalPerformances>
    </GetHistoricalKeywordPerformanceResponse>
  </s:Body>
</s:Envelope>

程式碼語法

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

public async Task<GetHistoricalKeywordPerformanceResponse> GetHistoricalKeywordPerformanceAsync(
	IList<string> keywords,
	TimeInterval? timeInterval,
	AdPosition? targetAdPosition,
	IList<MatchType> matchTypes,
	string language,
	IList<string> publisherCountries,
	IList<string> devices)
{
	var request = new GetHistoricalKeywordPerformanceRequest
	{
		Keywords = keywords,
		TimeInterval = timeInterval,
		TargetAdPosition = targetAdPosition,
		MatchTypes = matchTypes,
		Language = language,
		PublisherCountries = publisherCountries,
		Devices = devices
	};

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

static GetHistoricalKeywordPerformanceResponse getHistoricalKeywordPerformance(
	ArrayOfstring keywords,
	TimeInterval timeInterval,
	AdPosition targetAdPosition,
	ArrayOfMatchType matchTypes,
	java.lang.String language,
	ArrayOfstring publisherCountries,
	ArrayOfstring devices) throws RemoteException, Exception
{
	GetHistoricalKeywordPerformanceRequest request = new GetHistoricalKeywordPerformanceRequest();

	request.setKeywords(keywords);
	request.setTimeInterval(timeInterval);
	request.setTargetAdPosition(targetAdPosition);
	request.setMatchTypes(matchTypes);
	request.setLanguage(language);
	request.setPublisherCountries(publisherCountries);
	request.setDevices(devices);

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

static function GetHistoricalKeywordPerformance(
	$keywords,
	$timeInterval,
	$targetAdPosition,
	$matchTypes,
	$language,
	$publisherCountries,
	$devices)
{

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

	$request = new GetHistoricalKeywordPerformanceRequest();

	$request->Keywords = $keywords;
	$request->TimeInterval = $timeInterval;
	$request->TargetAdPosition = $targetAdPosition;
	$request->MatchTypes = $matchTypes;
	$request->Language = $language;
	$request->PublisherCountries = $publisherCountries;
	$request->Devices = $devices;

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

response=adinsight_service.GetHistoricalKeywordPerformance(
	Keywords=Keywords,
	TimeInterval=TimeInterval,
	TargetAdPosition=TargetAdPosition,
	MatchTypes=MatchTypes,
	Language=Language,
	PublisherCountries=PublisherCountries,
	Devices=Devices)

需求

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

共用方式為