GetKeywordIdeas 服務作業 - Ad Insight

發行項
12/21/2023

取得關鍵字想法的清單。

根據您現有的關鍵字、網站和產品類別，建議新的廣告群組和關鍵字。您也可以要求關鍵字的歷程記錄統計資料，例如每月搜尋、競賽、平均的一般一般、和廣告曝光率共用。您可以使用傳回的建議關鍵字標示作為 GetKeywordTrafficEstimates 作業的輸入。

提示

如需概觀，請參閱關鍵字構想和流量估計技術指南。

要求專案

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

注意事項

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

要求本文專案

元素	說明	資料類型
ExpandIdeas	判斷您想要新的關鍵字想法，還是只想要 SearchParameters 清單中指定的關鍵字集合的關鍵字屬性。如果您將此元素設定為 false，則 QuerySearchParameter 物件必須包含在 SearchParameters 清單中。	布林
IdeaAttributes	您想要包含在回應中的關鍵字概念屬性，例如關鍵字、競賽、 MonthlySearchCounts和 SuggestedBid。需要 [競賽] 屬性。無論您是否在所要求的概念屬性清單中包含 Keyword 值，一律會針對每個傳回的 KeywordIdea 傳回 Keyword 屬性。	KeywordIdeaAttribute 陣列
SearchParameters	搜尋參數會定義您所要求關鍵字想法的準則和篩選準則。請勿嘗試具現化 SearchParameter。您可以包含一或多個衍生自它的下列物件： CategorySearchParameter、 CompetitionSearchParameter、 DateRangeSearchParameter、 DeviceSearchParameter、 ExcludeAccountKeywordsSearchParameter、 IdeaTextSearchParameter、 ImpressionShareSearchParameter、 LanguageSearchParameter、 LocationSearchParameter、 NetworkSearchParameter、 QuerySearchParameter、 SearchVolumeSearchParameter、 SuggestedBidSearchParameter 和 UrlSearchParameter。衍生自 SearchParameter 的其他物件對此作業無效。您不能包含任何搜尋參數類型的重複專案。此清單必須包含所有這些搜尋參數： LanguageSearchParameter、 LocationSearchParameter和 NetworkSearchParameter。此清單必須包含其中一或多個搜尋參數： CategorySearchParameter、 QuerySearchParameter或 UrlSearchParameter。如果 ExpandIdeas 元素為 false，則無論您是否包含其他搜尋參數，都需要 QuerySearchParameter 。前一個日曆月份的資料最多可能需要 72 小時才能使用。例如，如果您在 8 月 1 日、2 日或 3 日要求關鍵字構想，且 7 月的資料尚未就緒，則回應會以 6 月的資料為基礎。如果您未在GetKeywordIdeas要求中包含DateRangeSearchParameter，則您將無法確認第一個清單專案是上個月或上個月的資料。如果指定日期範圍，但最近一個月的資料尚無法使用，則 GetKeywordIdeas 會傳回錯誤。	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 元素

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

回應本文專案

元素	說明	資料類型
KeywordIdeas	關鍵字想法的清單。目前最多可以傳回 3,000 個清單專案，但限制可能會變更。	KeywordIdea 數組

回應標頭元素

元素	說明	資料類型
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">GetKeywordIdeas</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>
    <GetKeywordIdeasRequest xmlns="https://bingads.microsoft.com/AdInsight/v13">
      <ExpandIdeas i:nil="false">ValueHere</ExpandIdeas>
      <IdeaAttributes i:nil="false">
        <KeywordIdeaAttribute>ValueHere</KeywordIdeaAttribute>
      </IdeaAttributes>
      <SearchParameters i:nil="false">
        <SearchParameter i:type="-- derived type specified here with the appropriate prefix --">
          <!--This field is applicable if the derived type attribute is set to QuerySearchParameter-->
          <Queries i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
            <a1:string>ValueHere</a1:string>
          </Queries>
          <!--This field is applicable if the derived type attribute is set to UrlSearchParameter-->
          <Url i:nil="false">ValueHere</Url>
          <!--This field is applicable if the derived type attribute is set to CategorySearchParameter-->
          <CategoryId>ValueHere</CategoryId>
          <!--These fields are applicable if the derived type attribute is set to SearchVolumeSearchParameter-->
          <Maximum i:nil="false">ValueHere</Maximum>
          <Minimum i:nil="false">ValueHere</Minimum>
          <!--These fields are applicable if the derived type attribute is set to SuggestedBidSearchParameter-->
          <Maximum i:nil="false">ValueHere</Maximum>
          <Minimum i:nil="false">ValueHere</Minimum>
          <!--These fields are applicable if the derived type attribute is set to IdeaTextSearchParameter-->
          <Excluded i:nil="false">
            <Keyword>
              <Id i:nil="false">ValueHere</Id>
              <MatchType>ValueHere</MatchType>
              <Text i:nil="false">ValueHere</Text>
            </Keyword>
          </Excluded>
          <Included i:nil="false">
            <Keyword>
              <Id i:nil="false">ValueHere</Id>
              <MatchType>ValueHere</MatchType>
              <Text i:nil="false">ValueHere</Text>
            </Keyword>
          </Included>
          <!--This field is applicable if the derived type attribute is set to ExcludeAccountKeywordsSearchParameter-->
          <ExcludeAccountKeywords>ValueHere</ExcludeAccountKeywords>
          <!--These fields are applicable if the derived type attribute is set to ImpressionShareSearchParameter-->
          <Maximum i:nil="false">ValueHere</Maximum>
          <Minimum i:nil="false">ValueHere</Minimum>
          <!--This field is applicable if the derived type attribute is set to LocationSearchParameter-->
          <Locations i:nil="false">
            <LocationCriterion>
              <LocationId>ValueHere</LocationId>
            </LocationCriterion>
          </Locations>
          <!--This field is applicable if the derived type attribute is set to NetworkSearchParameter-->
          <Network i:nil="false">
            <Network>ValueHere</Network>
          </Network>
          <!--This field is applicable if the derived type attribute is set to DeviceSearchParameter-->
          <Device i:nil="false">
            <DeviceName i:nil="false">ValueHere</DeviceName>
          </Device>
          <!--This field is applicable if the derived type attribute is set to LanguageSearchParameter-->
          <Languages i:nil="false">
            <LanguageCriterion>
              <Language i:nil="false">ValueHere</Language>
            </LanguageCriterion>
          </Languages>
          <!--This field is applicable if the derived type attribute is set to CompetitionSearchParameter-->
          <CompetitionLevels i:nil="false">
            <CompetitionLevel>ValueHere</CompetitionLevel>
          </CompetitionLevels>
          <!--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>
        </SearchParameter>
      </SearchParameters>
    </GetKeywordIdeasRequest>
  </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>
    <GetKeywordIdeasResponse xmlns="https://bingads.microsoft.com/AdInsight/v13">
      <KeywordIdeas d4p1:nil="false" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
        <KeywordIdea>
          <AdGroupId d4p1:nil="false">ValueHere</AdGroupId>
          <AdGroupName d4p1:nil="false">ValueHere</AdGroupName>
          <AdImpressionShare d4p1:nil="false">ValueHere</AdImpressionShare>
          <Competition d4p1:nil="false">ValueHere</Competition>
          <Keyword d4p1:nil="false">ValueHere</Keyword>
          <MonthlySearchCounts d4p1:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
            <a1:long>ValueHere</a1:long>
          </MonthlySearchCounts>
          <Relevance d4p1:nil="false">ValueHere</Relevance>
          <Source d4p1:nil="false">ValueHere</Source>
          <SuggestedBid d4p1:nil="false">ValueHere</SuggestedBid>
        </KeywordIdea>
      </KeywordIdeas>
    </GetKeywordIdeasResponse>
  </s:Body>
</s:Envelope>

程式碼語法

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

public async Task<GetKeywordIdeasResponse> GetKeywordIdeasAsync(
	bool? expandIdeas,
	IList<KeywordIdeaAttribute> ideaAttributes,
	IList<SearchParameter> searchParameters)
{
	var request = new GetKeywordIdeasRequest
	{
		ExpandIdeas = expandIdeas,
		IdeaAttributes = ideaAttributes,
		SearchParameters = searchParameters
	};

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

static GetKeywordIdeasResponse getKeywordIdeas(
	boolean expandIdeas,
	ArrayOfKeywordIdeaAttribute ideaAttributes,
	ArrayOfSearchParameter searchParameters) throws RemoteException, Exception
{
	GetKeywordIdeasRequest request = new GetKeywordIdeasRequest();

	request.setExpandIdeas(expandIdeas);
	request.setIdeaAttributes(ideaAttributes);
	request.setSearchParameters(searchParameters);

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

static function GetKeywordIdeas(
	$expandIdeas,
	$ideaAttributes,
	$searchParameters)
{

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

	$request = new GetKeywordIdeasRequest();

	$request->ExpandIdeas = $expandIdeas;
	$request->IdeaAttributes = $ideaAttributes;
	$request->SearchParameters = $searchParameters;

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

response=adinsight_service.GetKeywordIdeas(
	ExpandIdeas=ExpandIdeas,
	IdeaAttributes=IdeaAttributes,
	SearchParameters=SearchParameters)

需求

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

共用方式為