GetEstimatedBidByKeywords 服務作業 - Ad Insight

發行項
12/21/2023

取得一或多個關鍵字的估計中標價，這些關鍵字可能會導致廣告出現在搜尋結果中的目標位置。

估計值不是預測或保證未來的效能。

注意事項

這項作業適用于使用增強型的檢定標定策略的搜尋活動。

要求專案

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

注意事項

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

要求本文專案

元素	說明	資料類型
AdGroupId	廣告群組的識別碼，其效能資料可用來協助判斷關鍵字在廣告群組內容中的執行效能。指定廣告群組有助於改善建議的報價精確度。如果您指定廣告群組，則必須指定其所屬的行銷活動。	長
CampaignId	擁有 AdGroupId中指定之廣告群組的行銷活動識別碼。如果您未指定廣告群組，則會使用行銷活動的績效資料來協助判斷關鍵字在行銷活動內容中的執行效能。指定行銷活動和廣告群組有助於改善建議的報價精確度。如果未指定 AdGroupId 或 CampaignId ，作業會使用指定的 CustomerAccountId 標頭元素來協助判斷關鍵字在帳戶內容中的執行效能。	長
CurrencyCode	用於計算成本預估和建議的報價值之貨幣單位的 ISO 程式碼。如果未設定，服務會從 CustomerAccountId 標頭元素中指定的帳號決定貨幣。如果未設定 Currency 或 CustomerAccountId ，則服務會使用 USD。	CurrencyCode
EntityLevelBid	判斷是要傳回關鍵字層級的估計值、廣告群組層級的中標，還是兩者。 - 將 EntityLevelBid 設定為 Keyword，以取得對應至指定關鍵詞的 KeywordEstimatedBid 陣列。 - 將 EntityLevelBid 設定為 AdGroup 以取得指定廣告群組的一個 EstimatedBidAndTraffic 。 - 將 EntityLevelBid 設定為 AllEntities 以取得關鍵字的 KeywordEstimatedBid 陣列，以及廣告群組的一個 EstimatedBidAndTraffic 陣列。如果您未設定 EntityLevelBid，預設值是只傳回 KeywordEstimatedBid的陣列，或是將 EntityLevelBid 設定為 Keyword 的對等陣列。如果您將 EntityLevelBid 設定為Keyword、AdGroup 或 AllEntities 以外的任何值，服務會傳回 Code 3501 with ErrorCode CampaignServiceBidLevelInvalid。	string
關鍵字	KeywordAndMatchType資料物件的清單，您想要取得建議的標價值。您最多可以指定 1,000 個關鍵字，而且每個關鍵字最多可以包含 100 個字元。	KeywordAndMatchType 數組
語言	與位置識別碼平行使用的語言，用於預估報價。您在 LocationIds中指定的每個位置都必須支援該語言。如需可能的語言值，請參閱廣告語言。如果您未指定語言，服務作業會使用指定之 AdGroupId 或 CampaignId的語言。如果未設定這些屬性，則預設會使用 EN (英文) 。	string
LocationIds	用於估計報價的地理位置識別碼或識別碼。所有位置都必須支援 Language 元素中指定的語言。雖然您可以指定多個位置識別碼，但最佳做法是針對每個位置最精確的約定估計值，您應該針對每個服務呼叫只指定一個位置。如需可能的位置識別碼，請參閱地理位置代碼。如果您未指定任何位置，服務作業會使用指定之 AdGroupId 或 CampaignId的位置準則。如果未設定這些屬性，則預設會使用190 (美國) 。	long 陣列
TargetPositionForAds	您希望廣告出現在搜尋結果中的位置。預設值為 MainLine1。	TargetAdPosition

要求標頭元素

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

Response 元素

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

回應本文專案

元素	說明	資料類型
AdGroupEstimatedBid	包含按下次數的估計值、按一下 (時的平均成本) 、曝光數、點擊率 (CTR) ，以及如果您要使用建議的報價，則指定廣告群組的總成本。 EstimatedBidAndTraffic內的MatchType值一律為 Aggregate。在此內容中，它代表廣告群組的預設搜尋報價。	EstimatedBidAndTraffic
KeywordEstimatedBids	KeywordEstimatedBid資料物件的陣列。陣列包含要求中指定之每個關鍵字的專案。如果關鍵字無效，陣列中的對應專案將會是 Null。每個 KeywordEstimatedBid 都包含關鍵字和 EstimatedPositions 元素。如果關鍵字有可用的資料， EstimatedPositionAndTraffic 會提供可能造成廣告出現在搜尋結果目標位置的建議中。否則， EstimatedPositions 元素會設定為 null。	KeywordEstimatedBid 陣列

回應標頭元素

元素	說明	資料類型
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">GetEstimatedBidByKeywords</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>
    <GetEstimatedBidByKeywordsRequest xmlns="https://bingads.microsoft.com/AdInsight/v13">
      <Keywords i:nil="false">
        <KeywordAndMatchType>
          <KeywordText i:nil="false">ValueHere</KeywordText>
          <MatchTypes i:nil="false">
            <MatchType>ValueHere</MatchType>
          </MatchTypes>
        </KeywordAndMatchType>
      </Keywords>
      <TargetPositionForAds>ValueHere</TargetPositionForAds>
      <Language i:nil="false">ValueHere</Language>
      <LocationIds i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:long>ValueHere</a1:long>
      </LocationIds>
      <CurrencyCode i:nil="false">ValueHere</CurrencyCode>
      <CampaignId i:nil="false">ValueHere</CampaignId>
      <AdGroupId i:nil="false">ValueHere</AdGroupId>
      <EntityLevelBid i:nil="false">ValueHere</EntityLevelBid>
    </GetEstimatedBidByKeywordsRequest>
  </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>
    <GetEstimatedBidByKeywordsResponse xmlns="https://bingads.microsoft.com/AdInsight/v13">
      <KeywordEstimatedBids d4p1:nil="false" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
        <KeywordEstimatedBid>
          <Keyword d4p1:nil="false">ValueHere</Keyword>
          <EstimatedBids d4p1:nil="false">
            <EstimatedBidAndTraffic>
              <MinClicksPerWeek d4p1:nil="false">ValueHere</MinClicksPerWeek>
              <MaxClicksPerWeek d4p1:nil="false">ValueHere</MaxClicksPerWeek>
              <AverageCPC d4p1:nil="false">ValueHere</AverageCPC>
              <MinImpressionsPerWeek d4p1:nil="false">ValueHere</MinImpressionsPerWeek>
              <MaxImpressionsPerWeek d4p1:nil="false">ValueHere</MaxImpressionsPerWeek>
              <CTR d4p1:nil="false">ValueHere</CTR>
              <MinTotalCostPerWeek d4p1:nil="false">ValueHere</MinTotalCostPerWeek>
              <MaxTotalCostPerWeek d4p1:nil="false">ValueHere</MaxTotalCostPerWeek>
              <CurrencyCode>ValueHere</CurrencyCode>
              <MatchType>ValueHere</MatchType>
              <EstimatedMinBid>ValueHere</EstimatedMinBid>
            </EstimatedBidAndTraffic>
          </EstimatedBids>
        </KeywordEstimatedBid>
      </KeywordEstimatedBids>
      <AdGroupEstimatedBid d4p1:nil="false" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
        <MinClicksPerWeek d4p1:nil="false">ValueHere</MinClicksPerWeek>
        <MaxClicksPerWeek d4p1:nil="false">ValueHere</MaxClicksPerWeek>
        <AverageCPC d4p1:nil="false">ValueHere</AverageCPC>
        <MinImpressionsPerWeek d4p1:nil="false">ValueHere</MinImpressionsPerWeek>
        <MaxImpressionsPerWeek d4p1:nil="false">ValueHere</MaxImpressionsPerWeek>
        <CTR d4p1:nil="false">ValueHere</CTR>
        <MinTotalCostPerWeek d4p1:nil="false">ValueHere</MinTotalCostPerWeek>
        <MaxTotalCostPerWeek d4p1:nil="false">ValueHere</MaxTotalCostPerWeek>
        <CurrencyCode>ValueHere</CurrencyCode>
        <MatchType>ValueHere</MatchType>
        <EstimatedMinBid>ValueHere</EstimatedMinBid>
      </AdGroupEstimatedBid>
    </GetEstimatedBidByKeywordsResponse>
  </s:Body>
</s:Envelope>

程式碼語法

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

public async Task<GetEstimatedBidByKeywordsResponse> GetEstimatedBidByKeywordsAsync(
	IList<KeywordAndMatchType> keywords,
	TargetAdPosition targetPositionForAds,
	string language,
	IList<long> locationIds,
	CurrencyCode? currencyCode,
	long? campaignId,
	long? adGroupId,
	string entityLevelBid)
{
	var request = new GetEstimatedBidByKeywordsRequest
	{
		Keywords = keywords,
		TargetPositionForAds = targetPositionForAds,
		Language = language,
		LocationIds = locationIds,
		CurrencyCode = currencyCode,
		CampaignId = campaignId,
		AdGroupId = adGroupId,
		EntityLevelBid = entityLevelBid
	};

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

static GetEstimatedBidByKeywordsResponse getEstimatedBidByKeywords(
	ArrayOfKeywordAndMatchType keywords,
	TargetAdPosition targetPositionForAds,
	java.lang.String language,
	ArrayOflong locationIds,
	CurrencyCode currencyCode,
	java.lang.Long campaignId,
	java.lang.Long adGroupId,
	java.lang.String entityLevelBid) throws RemoteException, Exception
{
	GetEstimatedBidByKeywordsRequest request = new GetEstimatedBidByKeywordsRequest();

	request.setKeywords(keywords);
	request.setTargetPositionForAds(targetPositionForAds);
	request.setLanguage(language);
	request.setLocationIds(locationIds);
	request.setCurrencyCode(currencyCode);
	request.setCampaignId(campaignId);
	request.setAdGroupId(adGroupId);
	request.setEntityLevelBid(entityLevelBid);

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

static function GetEstimatedBidByKeywords(
	$keywords,
	$targetPositionForAds,
	$language,
	$locationIds,
	$currencyCode,
	$campaignId,
	$adGroupId,
	$entityLevelBid)
{

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

	$request = new GetEstimatedBidByKeywordsRequest();

	$request->Keywords = $keywords;
	$request->TargetPositionForAds = $targetPositionForAds;
	$request->Language = $language;
	$request->LocationIds = $locationIds;
	$request->CurrencyCode = $currencyCode;
	$request->CampaignId = $campaignId;
	$request->AdGroupId = $adGroupId;
	$request->EntityLevelBid = $entityLevelBid;

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

response=adinsight_service.GetEstimatedBidByKeywords(
	Keywords=Keywords,
	TargetPositionForAds=TargetPositionForAds,
	Language=Language,
	LocationIds=LocationIds,
	CurrencyCode=CurrencyCode,
	CampaignId=CampaignId,
	AdGroupId=AdGroupId,
	EntityLevelBid=EntityLevelBid)

需求

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

共用方式為