Partilhar via

Operação do Serviço GetHistoricalSearchCount - Ad Insight

  • Artigo

Obtém o número de vezes que o termo normalizado foi utilizado numa pesquisa durante o período de tempo especificado. Os resultados são agregados por tipo de dispositivo.

Elementos do Pedido

O objeto GetHistoricalSearchCountRequest define os elementos do corpo e do cabeçalho do pedido de operação do serviço. Os elementos têm de estar na mesma ordem mostrada no Pedido SOAP.

Nota

Salvo indicação em contrário abaixo, todos os elementos do pedido são necessários.

Elementos do Corpo do Pedido

Elemento Descrição Tipo de Dados
Dispositivos Uma lista de um ou mais dos seguintes tipos de dispositivo: Computadores, NãoArtphones, Smartphones, Tablets. A predefinição é Computadores.

A resposta inclui contagens de pesquisa para os tipos de dispositivo que especificar apenas, se disponíveis.		 matriz de cadeia
DataDadosEncom efeitos Finais A data de fim do intervalo de datas que identifica os dados que pretende utilizar para determinar a contagem de pesquisa histórica.

A data não pode ser posterior à data de hoje e tem de ser posterior ou igual à data de início especificada.

A data de fim efetiva pode ser ajustada se o TimePeriodRollup especificado for Semanal ou Mensal.		 DayMonthAndYear
Palavras-chave Uma matriz de palavras-chave para as quais pretende determinar o número de vezes que a palavra-chave foi utilizada numa consulta de pesquisa. A matriz pode conter um máximo de 1000 palavras-chave e cada palavra-chave pode conter um máximo de 100 carateres. matriz de cadeia
Idioma O idioma no qual as palavras-chave são escritas.

Os países/regiões que especificar no elemento PublisherCountries têm de suportar o idioma especificado.

Para obter valores possíveis, veja Idiomas Suportados.		 cadeia
PublisherCountries Os códigos de país dos países/regiões a utilizar como origem dos dados históricos.

Pode especificar um ou mais códigos de país. Cada país/região que especificar tem de suportar o idioma especificado no elemento Idioma .

Para obter valores possíveis, veja Idiomas de Anúncios.

Se For Nulo, a predefinição é todos os países/regiões que suportam o idioma especificado.		 matriz de cadeia
Data De Início A data de início do intervalo de datas que identifica os dados que pretende utilizar para determinar a contagem de pesquisa histórica.

Esta data tem de ser anterior ou igual à data de fim especificada. A data deve ser posterior ao intervalo máximo de dados históricos disponível correspondente ao elemento TimePeriodRollup especificado.

A data de início efetiva pode ser ajustada se o TimePeriodRollup especificado for Semanal ou Mensal.		 DayMonthAndYear
TimePeriodRollup Pode especificar se pretende devolver dados agregados diariamente, semanalmente ou mensalmente.

Para obter uma lista dos valores suportados, veja a secção Observações abaixo.		 cadeia

Elementos do Cabeçalho do Pedido

Elemento Descrição Tipo de Dados
AuthenticationToken O token de acesso OAuth que representa as credenciais de um utilizador que tem permissões para contas do Microsoft Advertising.

Para obter mais informações, veja Authentication with OAuth (Autenticação com OAuth).		 cadeia
CustomerAccountId O identificador da conta de anúncio que detém ou está associada às entidades no pedido. Este elemento de cabeçalho tem de ter o mesmo valor que o elemento do corpo AccountId quando ambos são necessários. Este elemento é necessário para a maioria das operações de serviço e, como melhor prática, deve sempre defini-lo.

Para obter mais informações, veja Obter a Sua Conta e IDs de Cliente.		 cadeia
CustomerId O identificador da conta de gestor (cliente) a partir da qual o utilizador está a aceder ou a operar. Um utilizador pode ter acesso a várias contas de gestor. Este elemento é necessário para a maioria das operações de serviço e, como melhor prática, deve sempre defini-lo.

Para obter mais informações, veja Obter a Sua Conta e IDs de Cliente.		 cadeia
DeveloperToken O token de programador utilizado para aceder à API de Anúncios do Bing.

Para obter mais informações, veja Obter um Token de Programador.		 cadeia
Palavra-passe Este elemento está reservado para utilização interna e será removido de uma versão futura da API. Tem de utilizar o elemento AuthenticationToken para definir credenciais de utilizador. cadeia
Nome de Utilizador Este elemento está reservado para utilização interna e será removido de uma versão futura da API. Tem de utilizar o elemento AuthenticationToken para definir credenciais de utilizador. cadeia

Elementos de Resposta

O objeto GetHistoricalSearchCountResponse define os elementos do corpo e do cabeçalho da resposta da operação do serviço. Os elementos são devolvidos pela mesma ordem mostrada no SOAP de Resposta.

Elementos do Corpo da Resposta

Elemento Descrição Tipo de Dados
KeywordSearchCounts Uma matriz de objetos de dados KeywordSearchCount . A matriz contém um item para cada palavra-chave especificada no pedido. Se a palavra-chave não for válida, o item correspondente na matriz será nulo.

Cada KeywordSearchCount contém uma matriz de SearchCountsByAttributes. A matriz contém um item para cada dispositivo exclusivo especificado no pedido.		 Matriz KeywordSearchCount

Elementos do Cabeçalho de Resposta

Elemento Descrição Tipo de Dados
TrackingId O identificador da entrada de registo que contém os detalhes da chamada à API. cadeia

Pedir SOAP

Este modelo foi gerado por uma ferramenta para mostrar a ordem dos elementos do corpo e do cabeçalho do pedido SOAP. Para tipos suportados que pode utilizar com esta operação de serviço, veja a referência Request Body Elements (Elementos do Corpo do Pedido ) acima.

<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">GetHistoricalSearchCount</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>
    <GetHistoricalSearchCountRequest 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>
      <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>
      <StartDate i:nil="false">
        <Day>ValueHere</Day>
        <Month>ValueHere</Month>
        <Year>ValueHere</Year>
      </StartDate>
      <EndDate i:nil="false">
        <Day>ValueHere</Day>
        <Month>ValueHere</Month>
        <Year>ValueHere</Year>
      </EndDate>
      <TimePeriodRollup i:nil="false">ValueHere</TimePeriodRollup>
      <Devices i:nil="false" xmlns:a1="http://schemas.microsoft.com/2003/10/Serialization/Arrays">
        <a1:string>ValueHere</a1:string>
      </Devices>
    </GetHistoricalSearchCountRequest>
  </s:Body>
</s:Envelope>

Soap de Resposta

Este modelo foi gerado por uma ferramenta para mostrar a ordem dos elementos do corpo e do cabeçalho para a resposta 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>
    <GetHistoricalSearchCountResponse xmlns="https://bingads.microsoft.com/AdInsight/v13">
      <KeywordSearchCounts d4p1:nil="false" xmlns:d4p1="http://www.w3.org/2001/XMLSchema-instance">
        <KeywordSearchCount>
          <Keyword d4p1:nil="false">ValueHere</Keyword>
          <SearchCountsByAttributes d4p1:nil="false">
            <SearchCountsByAttributes>
              <Device d4p1:nil="false">ValueHere</Device>
              <HistoricalSearchCounts d4p1:nil="false">
                <HistoricalSearchCountPeriodic>
                  <SearchCount>ValueHere</SearchCount>
                  <DayMonthAndYear d4p1:nil="false">
                    <Day>ValueHere</Day>
                    <Month>ValueHere</Month>
                    <Year>ValueHere</Year>
                  </DayMonthAndYear>
                </HistoricalSearchCountPeriodic>
              </HistoricalSearchCounts>
            </SearchCountsByAttributes>
          </SearchCountsByAttributes>
        </KeywordSearchCount>
      </KeywordSearchCounts>
    </GetHistoricalSearchCountResponse>
  </s:Body>
</s:Envelope>

Sintaxe de Código

A sintaxe de exemplo pode ser utilizada com os SDKs de Anúncios do Bing. Veja Exemplos de Código da API de Anúncios do Bing para obter mais exemplos.

public async Task<GetHistoricalSearchCountResponse> GetHistoricalSearchCountAsync(
	IList<string> keywords,
	string language,
	IList<string> publisherCountries,
	DayMonthAndYear startDate,
	DayMonthAndYear endDate,
	string timePeriodRollup,
	IList<string> devices)
{
	var request = new GetHistoricalSearchCountRequest
	{
		Keywords = keywords,
		Language = language,
		PublisherCountries = publisherCountries,
		StartDate = startDate,
		EndDate = endDate,
		TimePeriodRollup = timePeriodRollup,
		Devices = devices
	};

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

static GetHistoricalSearchCountResponse getHistoricalSearchCount(
	ArrayOfstring keywords,
	java.lang.String language,
	ArrayOfstring publisherCountries,
	DayMonthAndYear startDate,
	DayMonthAndYear endDate,
	java.lang.String timePeriodRollup,
	ArrayOfstring devices) throws RemoteException, Exception
{
	GetHistoricalSearchCountRequest request = new GetHistoricalSearchCountRequest();

	request.setKeywords(keywords);
	request.setLanguage(language);
	request.setPublisherCountries(publisherCountries);
	request.setStartDate(startDate);
	request.setEndDate(endDate);
	request.setTimePeriodRollup(timePeriodRollup);
	request.setDevices(devices);

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

static function GetHistoricalSearchCount(
	$keywords,
	$language,
	$publisherCountries,
	$startDate,
	$endDate,
	$timePeriodRollup,
	$devices)
{

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

	$request = new GetHistoricalSearchCountRequest();

	$request->Keywords = $keywords;
	$request->Language = $language;
	$request->PublisherCountries = $publisherCountries;
	$request->StartDate = $startDate;
	$request->EndDate = $endDate;
	$request->TimePeriodRollup = $timePeriodRollup;
	$request->Devices = $devices;

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

response=adinsight_service.GetHistoricalSearchCount(
	Keywords=Keywords,
	Language=Language,
	PublisherCountries=PublisherCountries,
	StartDate=StartDate,
	EndDate=EndDate,
	TimePeriodRollup=TimePeriodRollup,
	Devices=Devices)

Observações

Os seguintes valores sensíveis às maiúsculas e minúsculas podem ser especificados e os dados serão devolvidos até ao intervalo de dados histórico máximo disponível correspondente.

TimePeriodRollup Dados Históricos Disponíveis
Diariamente Até 45 dias antes do dia concluído mais recente.
Semanalmente Até 15 semanas antes da semana mais recente concluída.

O StartDate especificado é ajustado novamente para o domingo mais próximo e o EndDate é ajustado para o sábado mais próximo.
Mensalmente Até 24 meses antes do mês mais recente concluído.

O StartDate especificado é ajustado novamente para o início do mês e o EndDate é ajustado para o final do mês.

Idiomas Suportados

Seguem-se os idiomas suportados para o elemento Corpo do pedido de idioma :

Idiomas Suportados
Danish
Dutch
English
Finnish
French
German
Italian
Norueguês
Português
SimplifiedChinese
Spanish
Swedish
TradicionalChinês

Idiomas e Mapeamento de País/Região

Eis uma tabela de idiomas e mapeamento de país/região:

Idioma CountryCode País/Região Language@Country
Danish DK Dinamarca Danish@Denmark
Dutch NL Países Baixos Dutch@Netherlands
English AU Austrália English@Australia
English AC Canadá English@Canada
English FR França English@France
English DE Alemanha English@Germany
English IN Índia English@India
English ID Indonésia English@Indonesia
English IE Irlanda English@Ireland
English TI Itália English@Italy
English O MEU Malásia English@Malaysia
English NL Países Baixos English@Netherlands
English NZ NewZealand English@NewZealand
English PH Filipinas English@Philippines
English SG Singapura English@Singapore
English ES Espanha English@Spain
English SE Suécia English@Sweden
English CH Suíça English@Switzerland
English TH Tailândia English@Thailand
English GB Reino Unido English@UK
English E.U.A Estados Unidos English@US
English VN Vietname English@Vietnam
Finnish FI Finlândia Finnish@Finland
French AC Canadá French@Canada
French FR França French@France
French CH Suíça French@Switzerland
French GB Reino Unido French@UK
French E.U.A Estados Unidos French@US
German AU Austrália German@Australia
German AT Áustria German@Austria
German AC Canadá German@Canada
German FR França German@France
German DE Alemanha German@Germany
German CH Suíça German@Switzerland
German GB Reino Unido German@UK
German E.U.A Estados Unidos German@US
Italian TI Itália Italian@Italy
Norueguês NÃO Noruega Norwegian@Norway
Português BR Brasil Portuguese@Brazil
SimplifiedChinese CN China SimplifiedChinese@China
Spanish AR Argentina Spanish@Argentina
Spanish CL Chile Spanish@Chile
Spanish CO Colômbia Spanish@Colombia
Spanish MX México Spanish@Mexico
Spanish PE Peru Spanish@Peru
Spanish ES Espanha Spanish@Spain
Spanish E.U.A E.U.A Spanish@US
Spanish VE Venezuela Spanish@Venezuela
Swedish SE Suécia Swedish@Sweden
TradicionalChinês HK HongKongSAR TraditionalChinese@HongKongSAR
TradicionalChinês TW Taiwan TraditionalChinese@Taiwan

Requisitos

Serviço: AdInsightService.svc v13
Espaço de nomes: https://bingads.microsoft.com/AdInsight/v13