Operazione del servizio GetHistoricalKeywordPerformance - Ad Insight
Ottiene le prestazioni cronologica del termine di ricerca normalizzato. I risultati vengono aggregati in base al tipo di dispositivo.
Elementi della richiesta
L'oggetto GetHistoricalKeywordPerformanceRequest definisce il corpo e gli elementi di intestazione della richiesta di operazione del servizio. Gli elementi devono essere nello stesso ordine indicato nella richiesta SOAP.
Nota
Se non diversamente indicato di seguito, sono necessari tutti gli elementi della richiesta.
Elementi del corpo della richiesta
| Elemento | Descrizione | Tipo di dati |
|---|---|---|
| Dispositivi | Elenco di uno o più dei seguenti tipi di dispositivo: Computer, NonSmartphones, Smartphone, Tablet. Il valore predefinito è Computer. La risposta include dati sulle prestazioni delle parole chiave per i tipi di dispositivo specificati solo, se disponibili. Usato per determinare le prestazioni di una parola chiave nei tipi di dispositivo specificati. |
matrice di stringhe |
| Parole chiave | Matrice di parole chiave per cui si vogliono ottenere statistiche cronologice sulle prestazioni. La matrice può contenere un massimo di 1.000 parole chiave e ogni parola chiave può contenere un massimo di 100 caratteri. | matrice di stringhe |
| Lingua | Linguaggio in cui vengono scritte le parole chiave. I paesi/aree geografiche specificati nell'elemento PublisherCountries devono supportare la lingua specificata. I valori possibili includono danese, olandese, inglese, finlandese, francese, tedesco, italiano, norvegese, portoghese, spagnolo, svedese e cinese tradizionale. |
corda |
| MatchTypes | Tipi di corrispondenza per cui si vogliono ottenere dati cronologici. Non è possibile specificare il tipo di corrispondenza Contenuto. |
Matrice MatchType |
| PublisherCountries | Codici paese dei paesi/aree geografiche da usare come origine dei dati cronologici. È possibile specificare uno o più codici paese. Ogni paese/area geografica specificato deve supportare la lingua specificata nell'elemento Language . Sono supportate le combinazioni di lingua e paese/area geografica seguenti: Danese: DK Olandese: NL Inglese: AU, CA, GB, ID, IN, MY, PH, SG, TH, US, VN Finlandese: FI Francese: CA, FR Tedesco: AT, CH, DE Italiano: IT Norvegese: NB Portoghese: BR Spagnolo: AR, CL, CO, ES, MX, PE, VE Svedese: SE TradizionaleChinese: HK, TW Se questo elemento è Null, per impostazione predefinita il servizio include tutti i paesi/aree geografiche che supportano la lingua specificata. |
matrice di stringhe |
| TargetAdPosition | Posizione dei risultati della ricerca per cui si desidera ottenere i dati sulle prestazioni. Ad esempio, per ottenere i dati sulle prestazioni quando gli annunci vengono visualizzati nella prima posizione della linea principale usando la parola chiave e il tipo di corrispondenza, impostare questo elemento su MainLine1. Per ottenere i dati sulle prestazioni quando gli annunci vengono visualizzati in qualsiasi posizione dei risultati della ricerca usando la parola chiave e il tipo di corrispondenza, imposta questo elemento su Tutto. Il valore predefinito è All. Se si specifica All per questo elemento, il servizio restituirà più risultati per parola chiave per ogni posizione di annuncio supportata. Se si specifica Aggregate, il servizio restituirà un risultato aggregato. Gli annunci della barra laterale non vengono più pubblicati nei siti di proprietà e gestiti da Bing nel Stati Uniti. Se si richiedono solo i dati della prima pagina, ad esempio FirstPage1 per il Stati Uniti (US), l'elemento KeywordKPI nel risultato sarà nil/vuoto. Se si includono altri paesi/aree geografiche, ad esempio Stati Uniti e CA nella stessa richiesta, tutti i risultati della prima pagina vengono attribuiti solo a paesi/aree esterne alla Stati Uniti. |
AdPosition |
| TimeInterval | Periodo di tempo che identifica i dati da utilizzare per determinare l'indice delle prestazioni chiave delle parole chiave specificate. Ad esempio, usare i dati dei sette giorni precedenti o dei 30 giorni precedenti per determinare le prestazioni della parola chiave. Il valore predefinito è LastDay. |
TimeInterval |
Elementi dell'intestazione della richiesta
| Elemento | Descrizione | Tipo di dati |
|---|---|---|
| AuthenticationToken | Token di accesso OAuth che rappresenta le credenziali di un utente che dispone delle autorizzazioni per gli account Microsoft Advertising. Per altre informazioni, vedere Autenticazione con OAuth. |
corda |
| CustomerAccountId | Identificatore dell'account pubblicitario proprietario o associato alle entità nella richiesta. Questo elemento di intestazione deve avere lo stesso valore dell'elemento del corpo AccountId quando sono necessari entrambi. Questo elemento è necessario per la maggior parte delle operazioni del servizio e, come procedura consigliata, è consigliabile impostarlo sempre. Per altre informazioni, vedere Ottenere l'account e gli ID cliente. |
corda |
| CustomerId | Identificatore dell'account manager (cliente) da cui l'utente accede o opera. Un utente può avere accesso a più account manager. Questo elemento è necessario per la maggior parte delle operazioni del servizio e, come procedura consigliata, è consigliabile impostarlo sempre. Per altre informazioni, vedere Ottenere l'account e gli ID cliente. |
corda |
| DeveloperToken | Token di sviluppo usato per accedere all'API Bing Ads. Per altre informazioni, vedere Ottenere un token per sviluppatori. |
corda |
| Password | Questo elemento è riservato per l'uso interno e verrà rimosso da una versione futura dell'API. È necessario usare l'elemento AuthenticationToken per impostare le credenziali utente. | corda |
| UserName | Questo elemento è riservato per l'uso interno e verrà rimosso da una versione futura dell'API. È necessario usare l'elemento AuthenticationToken per impostare le credenziali utente. | corda |
Elementi di risposta
L'oggetto GetHistoricalKeywordPerformanceResponse definisce gli elementi corpo e intestazione della risposta dell'operazione del servizio. Gli elementi vengono restituiti nello stesso ordine illustrato nella soap di risposta.
Elementi del corpo della risposta
| Elemento | Descrizione | Tipo di dati |
|---|---|---|
| KeywordHistoricalPerformances | Matrice di oggetti dati KeywordHistoricalPerformance . La matrice contiene un elemento per ogni parola chiave, dispositivo, tipo di corrispondenza e posizione dell'annuncio specificata nella richiesta. Se la parola chiave non è valida o non dispone di dati disponibili, l'elemento corrispondente nella matrice sarà Null. | Matrice KeywordHistoricalPerformance |
Elementi dell'intestazione della risposta
| Elemento | Descrizione | Tipo di dati |
|---|---|---|
| TrackingId | Identificatore della voce di log che contiene i dettagli della chiamata API. | corda |
Richiedi SOAP
Questo modello è stato generato da uno strumento per visualizzare l'ordine degli elementi corpo e intestazione per la richiesta SOAP. Per i tipi supportati che è possibile usare con questa operazione del servizio, vedere il riferimento Request Body Elements sopra riportato.
<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 della risposta
Questo modello è stato generato da uno strumento per visualizzare l'ordine degli elementi del corpo e dell'intestazione per la risposta 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>
Sintassi del codice
La sintassi di esempio può essere usata con gli SDK di Bing Ads. Per altri esempi, vedere Esempi di codice DELL'API Bing Ads .
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)
Requisiti
Servizio: AdInsightService.svc v13
Namespace: https://bingads.microsoft.com/AdInsight/v13
URL richiesta
https://adinsight.api.bingads.microsoft.com/AdInsight/v13/HistoricalKeywordPerformance/Query
Elementi della richiesta
L'oggetto GetHistoricalKeywordPerformanceRequest definisce il corpo e gli elementi di intestazione della richiesta di operazione del servizio.
Nota
Se non diversamente indicato di seguito, sono necessari tutti gli elementi della richiesta.
Elementi del corpo della richiesta
| Elemento | Descrizione | Tipo di dati |
|---|---|---|
| Dispositivi | Elenco di uno o più dei seguenti tipi di dispositivo: Computer, NonSmartphones, Smartphone, Tablet. Il valore predefinito è Computer. La risposta include dati sulle prestazioni delle parole chiave per i tipi di dispositivo specificati solo, se disponibili. Usato per determinare le prestazioni di una parola chiave nei tipi di dispositivo specificati. |
matrice di stringhe |
| Parole chiave | Matrice di parole chiave per cui si vogliono ottenere statistiche cronologice sulle prestazioni. La matrice può contenere un massimo di 1.000 parole chiave e ogni parola chiave può contenere un massimo di 100 caratteri. | matrice di stringhe |
| Lingua | Linguaggio in cui vengono scritte le parole chiave. I paesi/aree geografiche specificati nell'elemento PublisherCountries devono supportare la lingua specificata. I valori possibili includono danese, olandese, inglese, finlandese, francese, tedesco, italiano, norvegese, portoghese, spagnolo, svedese e cinese tradizionale. |
corda |
| MatchTypes | Tipi di corrispondenza per cui si vogliono ottenere dati cronologici. Non è possibile specificare il tipo di corrispondenza Contenuto. |
Matrice MatchType |
| PublisherCountries | Codici paese dei paesi/aree geografiche da usare come origine dei dati cronologici. È possibile specificare uno o più codici paese. Ogni paese/area geografica specificato deve supportare la lingua specificata nell'elemento Language . Sono supportate le combinazioni di lingua e paese/area geografica seguenti: Danese: DK Olandese: NL Inglese: AU, CA, GB, ID, IN, MY, PH, SG, TH, US, VN Finlandese: FI Francese: CA, FR Tedesco: AT, CH, DE Italiano: IT Norvegese: NB Portoghese: BR Spagnolo: AR, CL, CO, ES, MX, PE, VE Svedese: SE TradizionaleChinese: HK, TW Se questo elemento è Null, per impostazione predefinita il servizio include tutti i paesi/aree geografiche che supportano la lingua specificata. |
matrice di stringhe |
| TargetAdPosition | Posizione dei risultati della ricerca per cui si desidera ottenere i dati sulle prestazioni. Ad esempio, per ottenere i dati sulle prestazioni quando gli annunci vengono visualizzati nella prima posizione della linea principale usando la parola chiave e il tipo di corrispondenza, impostare questo elemento su MainLine1. Per ottenere i dati sulle prestazioni quando gli annunci vengono visualizzati in qualsiasi posizione dei risultati della ricerca usando la parola chiave e il tipo di corrispondenza, imposta questo elemento su Tutto. Il valore predefinito è All. Se si specifica All per questo elemento, il servizio restituirà più risultati per parola chiave per ogni posizione di annuncio supportata. Se si specifica Aggregate, il servizio restituirà un risultato aggregato. Gli annunci della barra laterale non vengono più pubblicati nei siti di proprietà e gestiti da Bing nel Stati Uniti. Se si richiedono solo i dati della prima pagina, ad esempio FirstPage1 per il Stati Uniti (US), l'elemento KeywordKPI nel risultato sarà nil/vuoto. Se si includono altri paesi/aree geografiche, ad esempio Stati Uniti e CA nella stessa richiesta, tutti i risultati della prima pagina vengono attribuiti solo a paesi/aree esterne alla Stati Uniti. |
AdPosition |
| TimeInterval | Periodo di tempo che identifica i dati da utilizzare per determinare l'indice delle prestazioni chiave delle parole chiave specificate. Ad esempio, usare i dati dei sette giorni precedenti o dei 30 giorni precedenti per determinare le prestazioni della parola chiave. Il valore predefinito è LastDay. |
TimeInterval |
Elementi dell'intestazione della richiesta
| Elemento | Descrizione | Tipo di dati |
|---|---|---|
| Autorizzazione | Token di accesso OAuth che rappresenta le credenziali di un utente che dispone delle autorizzazioni per gli account Microsoft Advertising. Assicurarsi che il token sia preceduto da "Bearer", necessario per l'autenticazione corretta. Per altre informazioni, vedere Autenticazione con OAuth. |
corda |
| CustomerAccountId | Identificatore dell'account pubblicitario proprietario o associato alle entità nella richiesta. Questo elemento di intestazione deve avere lo stesso valore dell'elemento del corpo AccountId quando sono necessari entrambi. Questo elemento è necessario per la maggior parte delle operazioni del servizio e, come procedura consigliata, è consigliabile impostarlo sempre. Per altre informazioni, vedere Ottenere l'account e gli ID cliente. |
corda |
| CustomerId | Identificatore dell'account manager (cliente) da cui l'utente accede o opera. Un utente può avere accesso a più account manager. Questo elemento è necessario per la maggior parte delle operazioni del servizio e, come procedura consigliata, è consigliabile impostarlo sempre. Per altre informazioni, vedere Ottenere l'account e gli ID cliente. |
corda |
| DeveloperToken | Token di sviluppo usato per accedere all'API Bing Ads. Per altre informazioni, vedere Ottenere un token per sviluppatori. |
corda |
| Password | Questo elemento è riservato per l'uso interno e verrà rimosso da una versione futura dell'API. È necessario usare l'elemento AuthenticationToken per impostare le credenziali utente. | corda |
| UserName | Questo elemento è riservato per l'uso interno e verrà rimosso da una versione futura dell'API. È necessario usare l'elemento AuthenticationToken per impostare le credenziali utente. | corda |
Elementi di risposta
L'oggetto GetHistoricalKeywordPerformanceResponse definisce gli elementi corpo e intestazione della risposta dell'operazione del servizio. Gli elementi vengono restituiti nello stesso ordine illustrato nel codice JSON della risposta.
Elementi del corpo della risposta
| Elemento | Descrizione | Tipo di dati |
|---|---|---|
| KeywordHistoricalPerformances | Matrice di oggetti dati KeywordHistoricalPerformance . La matrice contiene un elemento per ogni parola chiave, dispositivo, tipo di corrispondenza e posizione dell'annuncio specificata nella richiesta. Se la parola chiave non è valida o non dispone di dati disponibili, l'elemento corrispondente nella matrice sarà Null. | Matrice KeywordHistoricalPerformance |
Elementi dell'intestazione della risposta
| Elemento | Descrizione | Tipo di dati |
|---|---|---|
| TrackingId | Identificatore della voce di log che contiene i dettagli della chiamata API. | corda |
Richiedere JSON
Questo modello è stato generato da uno strumento per visualizzare il corpo e gli elementi di intestazione per la richiesta JSON. Per i tipi supportati che è possibile usare con questa operazione del servizio, vedere il riferimento Request Body Elements sopra riportato.
{
"Keywords": [
"ValueHere"
],
"TimeInterval": "ValueHere",
"TargetAdPosition": "ValueHere",
"MatchTypes": [
"ValueHere"
],
"Language": "ValueHere",
"PublisherCountries": [
"ValueHere"
],
"Devices": [
"ValueHere"
]
}
Risposta JSON
Questo modello è stato generato da uno strumento per mostrare il corpo e gli elementi dell'intestazione per la risposta JSON.
{
"KeywordHistoricalPerformances": [
{
"Keyword": "ValueHere",
"KeywordKPIs": [
{
"AdPosition": "ValueHere",
"AverageBid": DoubleValueHere,
"AverageCPC": DoubleValueHere,
"Clicks": IntValueHere,
"CTR": DoubleValueHere,
"Device": "ValueHere",
"Impressions": "LongValueHere",
"MatchType": "ValueHere",
"TotalCost": DoubleValueHere
}
]
}
]
}
Sintassi del codice
Per chiamare l'API REST tramite SDK, è necessario aggiornare l'SDK a una determinata versione e configurare i parametri di sistema. La sintassi di esempio può essere usata con gli SDK di Bing Ads. Per altri esempi, vedere Esempi di codice DELL'API Bing Ads .
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)