Cerca riferimento all'API per Amazon CloudSearch - Amazon CloudSearch
CercaInvio di richieste di suggerimentoSuggerimentoErrori dei servizi di ricerca

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Cerca riferimento all'API per Amazon CloudSearch

Utilizzi l'API di ricerca per inviare richieste di ricerca o suggerimenti al tuo CloudSearch dominio Amazon. Per ulteriori informazioni sulla ricerca, vedi Ricerca nei tuoi dati con Amazon CloudSearch. Per ulteriori informazioni sui suggerimenti, vedi Ricevere suggerimenti di completamento automatico in Amazon CloudSearch.

Le altre API che usi per interagire con Amazon CloudSearch sono:

Cerca

In questa sezione vengono descritti i messaggi di richiesta e risposta HTTP per la risorsa di ricerca.

Sintassi di ricerca

GET /2013-01-01/search

Intestazioni delle richieste di ricerca

HOST

L'endpoint delle richieste di ricerca per il dominio sottoposto a query. Puoi utilizzare DescribeDomains per recuperare l'endpoint delle richieste di ricerca del dominio.

Campo obbligatorio: sì

Parametri delle richieste di ricerca

cursor

Recupera un valore di cursore che puoi utilizzare per scorrere set di risultati i grandi dimensioni. Utilizza il parametro size per controllare il numero di occorrenze da includere in ogni risposta. In una richiesta è possibile specificare o il parametro cursor o il parametro start, in quanto si escludono a vicenda. Per ulteriori informazioni, consulta Paginate the results.

Per ottenere il primo cursore, specifica cursor=initial nella tua richiesta iniziale. Nelle richieste successive specifica il valore di cursore restituito nella sezione delle occorrenze della risposta.

Ad esempio, i set di richieste seguenti impostano il valore del cursore su initial e il parametro size su 100 per ottenere il primo set di occorrenze. Il cursore per il set di occorrenze successivo è incluso nella risposta.

search?q=john&cursor=initial&size=100&return=_no_fields
{
   "status": {
      "rid": "+/Xu5s0oHwojC6o=",
      "time-ms": 15
   },
   "hits": {
      "found": 503,
      "start": 0,
      "cursor": "VegKzpYYQW9JSVFFRU1UeWwwZERBd09EUTNPRGM9ZA",
      "hit": [
         {"id": "tt0120601"},
         {"id": "tt1801552"},
         ...
      ]
   }
}

Per ottenere il set di occorrenze successivo, è necessario specificare il valore de cursore e il numero di occorrenze da recuperare.

search?q=john&cursor=VegKzpYYQW9JSVFFRU1UeWwwZERBd09EUTNPRGM9ZA&size=100

Tipo: string

Campo obbligatorio: no

expr.NAME

Definisce un'espressione che può essere utilizzata per ordinare i risultati. È anche possibile specificare un'espressione come campo incluso nei risultati. Per ulteriori informazioni sulla definizione e sull'utilizzo delle espressioni, vedi Configurazione di espressioni.

È possibile definire e utilizzare più espressioni in una richiesta di ricerca. Ad esempio, la seguente richiesta crea due espressioni che vengono utilizzate per ordinare i risultati e le include nei risultati della ricerca:

search?q=(and (term field=genres 'Sci-Fi')(term field=genres 'Comedy'))&q.parser=structured
&expr.expression1=_score*rating
&expr.expression2=(1/rank)*year
&sort=expression1 desc,expression2 desc
&return=title,rating,rank,year,_score,expression1,expression2

Tipo: string

Campo obbligatorio: no

facet.FIELD

Speciifica un campo per il quale desideri ottenere informazioni sui facet: FIELD è il nome del campo. Il campo specificato deve essere abilitato per i facet nella configurazione del dominio. Le opzioni dei facet sono specificate come oggetto JSON. Se l'oggetto JSON è vuoto, facet.FIELD={}, il numero di facet viene calcolato per tutti i valori dei campi, i facet vengono archiviati in base al loro numero e nei risultati vengono restituiti i primi 10 facet.

Puoi specificare tre opzioni nell'oggetto JSON:

  • sort specifica il modo in cui si desidera ordinare i facet nei risultati: bucket o count. Specifica bucket per impostare l'ordine alfabetico o numerico in base al valore di facet (in ordine crescente). Specifica count per ordinare i facet in base ai conteggi calcolati per ciascun valore di facet (in ordine decrescente). Per recuperare i conteggi dei facet per determinati valori o intervalli di valori, utilizza l'opzione buckets anziché sort.

  • buckets specifica una serie di valori o intervalli di facet da conteggiare. I bucket vengono restituiti nell'ordine in cui sono specificati nella richiesta. Per specificare un intervallo di valori, utilizza una virgola (,) per separare i limiti superiore e inferiore e inserisci l'intervallo tra parentesi tonde o parentesi graffe. Una parentesi quadra, [o], indica che il limite è incluso nell'intervallo, una parentesi graffa, {o}, esclude il limite. Puoi omettere il limite superiore o inferiore per specificare un intervallo aperto. Quando si omette un limite, è necessario utilizzare un tutore riccio. Le size opzioni sort and non sono valide se specificate. buckets

  • size specifica il numero massimo di facet da includere nei risultati. Per impostazione predefinita, i CloudSearch resi di Amazon rientrano tra i primi 10. Il parametro size è valido solo quando si specifica l'opzione sort, ma non può essere utilizzato in combinazione con buckets.

Ad esempio, la seguente richiesta ottiene i conteggi dei facet per il campo year, ordina i conteggi dei facet in base al valore e restituisce i conteggi per i primi tre:

facet.year={sort:"bucket", size:3}

Per specificare i valori o l'intervallo di valori per cui calcolare i conteggi dei facet, utilizza l'opzione buckets. Ad esempio, la seguente richiesta calcola e restituisce i conteggi dei facet in base alla decade:

facet.year={buckets:["[1970,1979]","[1980,1989]",
             "[1990,1999]","[2000,2009]",
             "[2010,}"]}

È anche possibile specificare valori singoli come bucket:

facet.genres={buckets:["Action","Adventure","Sci-Fi"]}

Per i valori dei facet viene fatta distinzione tra maiuscole e minuscole; con i dati dei film IMDb di esempio, se si specifica ["action","adventure","sci-fi"] anziché ["Action","Adventure","Sci-Fi"], tutti i conteggi dei facet sono pari a zero.

Tipo: string

Campo obbligatorio: no

format

Specifica il tipo di contenuti della risposta.

Tipo: stringa

Valori validi: json|xml

Impostazione predefinita: json

Campo obbligatorio: no

fq

Specifica una query strutturata che filtra i risultati di una ricerca senza modificare il modo in cui i risultati vengono valutati e ordinati. Utilizza fq in combinazione con il parametro q per filtrare i documenti che soddisfano i vincoli specificati nel parametro q. L'applicazione di un filtro consente semplicemente di controllare i documenti corrispondenti che vengono inclusi nei risultati, senza influenzare il modo in cui vengono valutati e ordinati. Il parametro fq supporta la sintassi delle query strutturate. Per ulteriori informazioni sull'uso dei filtri, vedi Filtraggio dei documenti corrispondenti. Per ulteriori informazioni sulle query strutturate, vedi Sintassi di ricerca strutturata.

Tipo: string

Campo obbligatorio: no

highlight.FIELD

Recupera evidenziazioni per le corrispondenze nel campo text o text-array specificato. Le opzioni di evidenziazione sono specificate come oggetto JSON. Se l'oggetto JSON è vuoto, il testo del campo restituito viene trattato come testo HTML e la prima corrispondenza viene evidenziata con tag di enfasi: <em>search-term</em>.

Puoi specificare quattro opzioni nell'oggetto JSON:

  • format—specifica il formato dei dati nel campo di testo: text o. html Quando i dati vengono restituiti come HTML, tutti i caratteri non alfanumerici vengono codificati. Il valore predefinito è html.

  • max_phrases—specifica il numero massimo di occorrenze dei termini di ricerca che si desidera evidenziare. Per impostazione predefinita, la prima occorrenza è evidenziata.

  • pre_tag—specifica la stringa da anteporre a un'occorrenza di un termine di ricerca. Il valore predefinito per le evidenziazioni HTML è <em>. Il valore predefinito per le evidenziazioni di testo è *.

  • post_tag—specifica la stringa da aggiungere a un'occorrenza di un termine di ricerca. Il valore predefinito per le evidenziazioni HTML è </em>. Il valore predefinito per le evidenziazioni di testo è *.

Esempi: highlight.plot={}, highlight.plot={format:'text',max_phrases:2,pre_tag:'<b>',post_tag:'</b>'}

Tipo: string

Campo obbligatorio: no

partial

Controlla se vengono restituiti risultati parziali se una o più partizioni di indice non sono disponibili. Quando l'indice di ricerca è partizionato su più istanze di ricerca, per impostazione predefinita Amazon restituisce risultati CloudSearch solo se è possibile interrogare ogni partizione. Ciò significa che l'errore di una singola istanza di ricerca può portare a errori di server interni (5xx). Quando lo specifichi. partial=true Amazon CloudSearch restituisce tutti i risultati disponibili e include la percentuale di documenti cercati nei risultati di ricerca (percent-searched). Ciò consente di attenuare la carenza dei risultati della ricerca agli occhi degli utenti. Ad esempio, invece di non visualizzare alcun risultato, è possibile visualizzare i risultati parziali e un messaggio che indica che i risultati potrebbero essere incompleti a causa di un'interruzione temporanea del sistema.

Tipo: Booleano

Impostazione predefinita: False

Campo obbligatorio: no

pretty

Formatta l'output JSON; in modo da renderlo più facilmente leggibile.

Tipo: Booleano

Impostazione predefinita: False

Campo obbligatorio: no

q

I criteri di ricerca per la richiesta. Il modo in cui si specificano criteri di ricerca dipende dal parser di query utilizzato per la richiesta e dalle opzioni di parser specificate nel parametro q.options. Per impostazione predefinita, il parser di query simple viene utilizzato per elaborare le richieste. Per utilizzare il parser di query structured, lucene o dismax, è necessario specificare anche il parametro q.parser. Per ulteriori informazioni sulla specifica dei criteri di ricerca, vedi Ricerca nei tuoi dati con Amazon CloudSearch.

Tipo: stringa

Campo obbligatorio: sì

q.options

Puoi configurare le opzioni per il parser di query specificato nel parametro q.parser. Le opzioni sono specificate come oggetto JSON, ad esempio: q.options={defaultOperator: 'or', fields: ['title^5','description']}.

Le opzioni che è possibile configurare variano in base al parser utilizzato:

  • defaultOperator—L'operatore predefinito utilizzato per combinare singoli termini nella stringa di ricerca. Ad esempio: defaultOperator: 'or'. Per il parser dismax, è necessario specificare un valore che rappresenta la percentuale di termini della stringa di ricerca (arrotondata per difetto) che deve corrispondere, anziché un operatore predefinito. Il valore 0% equivale a OR e il valore 100% equivale a AND. La percentuale deve essere specificata come valore compreso nell'intervallo 0-100, seguito dal simbolo di percentuale (%). Ad esempio, defaultOperator: 50%. Valori validi: and, or, una percentuale nell'intervallo 0%-100% (dismax). Impostazione predefinita: and (simple, structured, lucene) o 100 (dismax). Valida per: simple, structured, lucene e dismax.

  • fields—Una matrice dei campi in cui eseguire la ricerca quando non è specificato alcun campo in una ricerca. Se in una ricerca non sono specificati campi e non è specificata questa opzione, la ricerca viene eseguita in tutti i campi text e text-array configurati staticamente. Puoi specificare un peso per ogni campo per controllare l'importanza relativa di ogni campo quando Amazon CloudSearch calcola i punteggi di pertinenza. Per specificare una rilevanza del campo, aggiungi un accento circonflesso (^) e la rilevanza al nome del campo. Ad esempio, per aumentare la rilevanza del campo title rispetto al campo description, è possibile specificare: fields: ['title^5','description']. Valori validi: il nome di qualsiasi campo configurato e un valore numerico facoltativo maggiore di zero. Impostazione predefinita: tutti i campi text e text-array configurati staticamente. Per impostazione predefinita, i campi dinamici e i campi literal non sono oggetto di ricerca. Valida per: simple, structured, lucene e dismax.

  • operators—Un array di operatori o caratteri speciali che desideri disabilitare per il semplice parser di query. Se si disabilitano gli operatori and, or o not, gli operatori corrispondenti (+, |, -) non hanno alcun significato speciale e vengono eliminati dalla stringa di ricerca. Analogamente, disabilitando prefix si disabilita l'operatore carattere jolly (*) e disabilitando phrase si disabilita la possibilità di cercare periodi racchiudendoli tra doppie virgolette. Disabilitando la precedenza si disabilita la possibilità di controllare l'ordine di precedenza utilizzando le parentesi. Disabilitando near si disabilita la possibilità di utilizzare l'operatore ~ per eseguire una ricerca di frasi simili. La disabilitazione dell'operatore fuzzy disabilita la possibilità di utilizzare l'operatore ~ per eseguire una ricerca fuzzy. escape disabilita la possibilità di utilizzare una barra rovesciata (\) per inserire caratteri speciali di escape all'interno della stringa di ricerca. La disabilitazione dello spazio è un'opzione avanzata che impedisce al parser di trasformare le stringhe in token in corrispondenza degli spazi e che può essere utile per il vietnamita (impedisce la separazione non corretta delle parole vietnamite). Ad esempio, è possibile disabilitare tutti gli operatori diversi dall'operatore periodo per supportare solo le query di termini e periodi semplici: operators:['and', 'not', 'or', 'prefix']. Valori validi: and, escape, fuzzy, near, not, or, phrase, precedence, prefix, whitespace. Impostazione predefinita: tutti gli operatori e i caratteri speciali sono abilitati. Valida per: simple.

  • phraseFields—Una matrice dei text-array campi text o che si desidera utilizzare per la ricerca di frasi. Quando i termini della stringa di ricerca appaiono molto vicini all'interno di un campo, il campo ha un punteggio più elevato. È possibile aumentare tale punteggio specificando una rilevanza per ogni campo. L'opzione phraseSlop controlla in che misura le corrispondenze possono discostarsi dalla stringa di ricerca e avere comunque una rilevanza elevata. Per specificare una rilevanza del campo, aggiungi un accento circonflesso (^) e la rilevanza al nome del campo. Ad esempio, per aumentare la rilevanza delle corrispondenze dei periodi nel campo title rispetto al campo abstract, è possibile specificare: phraseFields:['title^3', 'abstract'] Valori validi: il nome di un campo text o text-array e un valore numerico facoltativo maggiore di zero. Impostazione predefinita: nessun campo. Se non specifichi un campo con phraseFields, l'assegnazione del punteggio di prossimità è disabilitato, anche se phraseSlop è specificato. Valida per: dismax.

  • phraseSlop—Un valore intero che specifica in che misura le corrispondenze possono deviare dalla frase di ricerca e comunque essere aumentate in base ai pesi specificati nell'opzione. phraseFields Ad esempio, phraseSlop: 2. Inoltre, è necessario specificare phraseFields per abilitare l'assegnazione del punteggio di prossimità. Valori validi: numeri interi positivi. Impostazione predefinita: 0. Valida per: dismax.

  • explicitPhraseSlop—Un valore intero che specifica in che misura una corrispondenza può deviare dalla frase di ricerca quando la frase è racchiusa tra virgolette doppie nella stringa di ricerca. (Le frasi che superano questa distanza di prossimità non sono considerate una corrispondenza.) explicitPhraseSlop: 5. Valori validi: numeri interi positivi. Impostazione predefinita: 0. Valida per: dismax.

  • tieBreaker—Quando un termine nella stringa di ricerca viene trovato nel campo di un documento, viene calcolato un punteggio per quel campo in base alla frequenza della parola in quel campo rispetto ad altri documenti. Se il termine viene utilizzato in più campi all'interno di un documento, per impostazione predefinita al punteggio globale del documento contribuisce solo il campo con punteggio più alto. È possibile specificare un valore tieBreaker per consentire che le corrispondenze nei campi con punteggio inferiore contribuiscano al punteggio del documento. In questo modo, se due documenti hanno lo stesso punteggio di campo massimo per un determinato termine, il documento con corrispondenze in più campi avrà un punteggio più alto. La formula per calcolare il punteggio con un tieBreaker è:

    (max field score) + (tieBreaker) * (sum of the scores for the rest of the matching fields)

    Ad esempio, la query seguente cerca il termine dog nei campi title, description e review e imposta tieBreaker su 0.1:

    q=dog&q.parser=dismax&q.options={fields:['title', 'description', 'review'], tieBreaker: 0.1}

    Se dog è presente in tutti e tre i campi di un documento e i punteggi per ogni campo sono title= 1, description= 3 e review = 1, il punteggio globale per il termine dog è:

    3 +  0.1 * (1+1) = 3.2

    Imposta tieBreaker su 0 per ignorare tutti i campi, ad eccezione di quello con punteggio più alto (max). Imposta su 1 per sommare i punteggi di tutti i campi (sum). Valori validi: da 0.0 a 1.0. Impostazione predefinita: 0.0. Valida per: dismax.

Tipo: oggetto JSON

Impostazione predefinita: vedi le descrizioni delle singole opzioni.

Campo obbligatorio: no

q.parser

Specifica quali parser di query utilizzare per elaborare la richiesta: simple, structured, lucene e dismax. Se non q.parser è specificato, Amazon CloudSearch utilizza il parser di simple query.

  • simple—esegue ricerche semplici su e campi. text text-array Per impostazione predefinita, il parser di query simple esegue la ricerca in tutti i campi text e text-array configurati staticamente. Puoi specificare i campi in cui desideri eseguire le ricerche con il parametro q.options. Se anteponi a un termine di ricerca il prefisso del segno più (+), per essere considerata una corrispondenza i documenti devono includere il termine (questa è l'impostazione predefinita, a meno che non si configuri l'operatore predefinito con il parametro q.options). È possibile utilizzare gli operatori - (NOT), | (OR) e * (carattere jolly) per escludere particolari termini, trovare i risultati che corrispondono a uno qualsiasi dei termini specificati oppure cercare un prefisso. Per cercare un periodo anziché singoli termini, racchiudi il periodo tra virgolette doppie. Per ulteriori informazioni, consulta Ricerca nei tuoi dati con Amazon CloudSearch.

  • structured—esegue ricerche avanzate combinando più espressioni per definire i criteri di ricerca. È inoltre possibile eseguire ricerche all'interno di campi specifici, cercare valori e intervalli di valori e utilizzare opzioni avanzate come l'aumento di rilevanza dei termini, matchall, e near. Per ulteriori informazioni, consulta Creazione di query composte.

  • lucene—ricerca utilizzando la sintassi del parser di query di Apache Lucene. Per ulteriori informazioni, consultare l'argomento relativo alla sintassi del parser di query Apache Lucene.

  • dismax—ricerca utilizzando il sottoinsieme semplificato della sintassi del parser di query Apache Lucene definita dal parser di query. DisMax Per ulteriori informazioni, vedere Query Parser Syntax. DisMax

Tipo: stringa

Impostazione predefinita: simple

Campo obbligatorio: no

return

I valori dei campi e delle espressioni da includere nella risposta, specificati come elenco separato da virgole. Per impostazione predefinita, una risposta di ricerca comprende tutti i campi inclusi nei risultati (return=_all_fields). Per restituire solo gli ID dei documenti corrispondenti, specifica return=_no_fields. Per recuperare il punteggio di rilevanza calcolato per ogni documento, specifica return=_score. È possibile specificare più campi inclusi nei risultati come elenco separato da virgole. Ad esempio, return=title,_score restituisce solo il titolo e il punteggio di rilevanza di ogni documento corrispondente.

Tipo: string

Campo obbligatorio: no

size

Il numero massimo di occorrenze di ricerca da restituire.

Tipo: numero intero positivo

Impostazione predefinita: 10

Campo obbligatorio: no

sort

Elenco separato da virgole di campi o espressioni personalizzate da utilizzare per ordinare i risultati della ricerca. È necessario specificare la direzione dell'ordinamento (asc o desc) per ciascun campo. Ad esempio, sort=year desc,title asc. È possibile specificare un massimo di 10 campi ed espressioni. Per usare un campo per ordinare i risultati, è necessario che il campo consenta l'ordinamento nella configurazione del dominio. I campi di tipo array non possono essere utilizzati per l'ordinamento. Se non viene specificato alcun parametro sort, i risultati sono elencati in base al punteggio di rilevanza in ordine decrescente: sort=_score desc. È possibile ordinarli anche in base all'ID documento (sort=_id) e alla versione (sort=_version).

Tipo: string

Campo obbligatorio: no

start

L'offset della prima occorrenza di ricerca che si desidera restituire. In una richiesta è possibile specificare o il parametro start o il parametro cursor, in quanto si escludono a vicenda. Per ulteriori informazioni, consulta Paginate the results.

Tipo: numero intero positivo

Impostazione predefinita: 0 (la prima occorrenza)

Campo obbligatorio: no

Sintassi di ricerca strutturata

Utilizza la sintassi di ricerca CloudSearch strutturata di Amazon per definire i criteri di ricerca quando usi il parser di structured query e per specificare i criteri di filtro con il fq parametro.

Quando utilizzi gli operatori delle query strutturate, devi specificare il nome dell'operatore, le relative opzioni e i termini a cui viene applicato l'operatore, (OPERATOR OPTIONS STRING|EXPRESSION). Qualsiasi opzione deve essere specificata prima della stringa o dell'espressione. Ad esempio, (and (not field=genres 'Sci-Fi')(or (term field=title boost=2 'star')(term field=plot 'star'))).

Importante

I caratteri speciali nella stringa di query devono essere codificati in formato URL. Ad esempio, devi codificare l'=operatore in una query strutturata come%3D:). (term+field%3Dtitle+'star' Amazon CloudSearch restituisce un InvalidQueryString errore se i caratteri speciali non sono codificati nell'URL. Per un riferimento completo delle codifiche nel formato URL, consultare il documento HTML URL Encoding Reference di W3C.

Se non si specifica il campo in cui si desidera eseguire la ricerca quando si usa il parser di query strutturate, la ricerca viene eseguita in tutti i campi text e text-array configurati staticamente. Per impostazione predefinita, i campi dinamici e i campi literal non sono oggetto di ricerca. Puoi indicare i campi in cui desideri eseguire la ricerca per impostazione predefinita specificando il parametro q.options.

Le parentesi controllano l'ordine di valutazione delle espressioni in una query composta. Se è racchiusa tra parentesi, un'espressione viene valutata per prima, quindi il valore risultante viene utilizzato nella valutazione della parte rimanente della query. Le espressioni possono contenere uno qualsiasi degli operatori di query strutturata.

È inoltre possibile utilizzare il parser di query strutturate per cercare una semplice stringa di testo: è sufficiente racchiudere la stringa da cercare tra virgolette singole: q='black swan'&q.parser="structured".

Per ulteriori informazioni sulla creazione di query composte con gli operatori di query strutturata, vedi Creazione di query composte.

FIELD

Sintassi: FIELD: 'STRING'|value

Cerca nel campo specificato una stringa, un valore numerico, una data o un intervallo di valori numerici o date.

Le stringhe devono essere racchiuse tra virgolette singole. Ogni singola virgoletta o barra rovesciata nella stringa deve essere sostituita da una barra rovesciata. Per specificare un intervallo di valori, utilizza una virgola (,) per separare i limiti superiore e inferiore e inserisci l'intervallo tra parentesi tonde o parentesi graffe. Una parentesi quadra, [o], indica che il limite è incluso nell'intervallo, una parentesi graffa, {o}, esclude il limite. Puoi omettere il limite superiore o inferiore per specificare un intervallo aperto. Quando si omette un limite, è necessario utilizzare un tutore riccio.

Le date e gli orari sono specificati in UTC (Coordinated Universal Time) secondo IETF RFC3339:. yyyy-mm-ddTHH:mm:ss.SSSZ In UTC, ad esempio, le 17:00 del 23 agosto 1970 sono:. 1970-08-23T17:00:00Z Tieni presente che puoi anche specificare frazioni di secondo quando specifichi gli orari in UTC. Ad esempio, 1967-01-31T23:20:50.650Z.

Esempi: 

title:'star'
year:2000
year:[1998,2000]
year:{,2011]
release_date:['2013-01-01T00:00:00Z',}
and

Sintassi: (and boost=N EXPRESSION EXPRESSION ... EXPRESSIONn)

Include un documento solo se corrisponde a tutte le espressioni specificate. (Operatore AND booleano.) Le espressioni possono contenere uno qualsiasi degli operatori di query strutturata o una stringa di ricerca semplice. Le stringhe di ricerca devono essere racchiuse tra virgolette singole. Per trovare la corrispondenza con i documenti che contengono i termini specificati nei campi in cui viene eseguita la ricerca, è necessario specificare ogni termine come espressione separata: (and 'star' 'wars'). Se si specifica (and 'star wars'), star e wars devono essere presenti nello stesso campo per essere considerati una corrispondenza.

Il valore boost è un valore numerico positivo che aumenta l'importanza di questa parte della query di ricerca rispetto alle altre parti.

Esempio: 

(and title:'star' actors:'Harrison Ford' year:{,2000])
matchall

Sintassi: matchall

Restituisce ogni documento del dominio. Per impostazione predefinita, restituisce i primi 10. Usa i parametri size e start per scorrere i risultati.

near

Sintassi: (near field=FIELD distance=N boost=N 'STRING')

Esegue la ricerca in un campo text o text-array della stringa a più termini specificata restituisce i documenti che contengono i termini a una distanza reciproca non superiore a quella specificata (A volte viene chiamata ricerca di frasi sciatta.) Se ometti l'fieldopzione, Amazon CloudSearch cerca tutti i text-array campi text e i campi configurati staticamente per impostazione predefinita. Per impostazione predefinita, i campi dinamici e i campi literal non sono oggetto di ricerca. Puoi specificare quali campi desideri cercare per impostazione predefinita specificando l'opzione. q.options fields

Il valore della distanza deve essere un numero intero positivo. Ad esempio, per trovare tutti i documenti in cui il termine teenage è presente a non più di 10 parole di distanza da vampire nel campo plot, è necessario specificare il valore di distanza 10: (near field=plot distance=10 'teenage vampire').

Il valore boost è un valore numerico positivo che aumenta l'importanza di questa parte della query di ricerca rispetto alle altre parti.

Esempio: 

(near field=plot distance=10 'teenage vampire')
not

Sintassi: (not boost=N EXPRESSION)

Esclude un documento se corrisponde all'espressione specificata. (Operatore NOT booleano). L'espressione può contenere uno qualsiasi degli operatori di query strutturata o una stringa di ricerca semplice. Le stringhe di ricerca devono essere racchiuse tra virgolette singole.

Il valore boost è un valore numerico positivo che aumenta l'importanza di questa parte della query di ricerca rispetto alle altre parti.

Esempio: 

(not (or actors:'Harrison Ford' year:{,2010]))
or

Sintassi: (or boost=N EXPRESSION1 EXPRESSION2 ... EXPRESSIONn)

Include un documento se corrisponde a una delle espressioni specificate. (Operatore OR booleano). Le espressioni possono contenere uno qualsiasi degli operatori di query strutturata o una stringa di ricerca semplice. Le stringhe di ricerca devono essere racchiuse tra virgolette singole.

Il valore boost è un valore numerico positivo che aumenta l'importanza di questa parte della query di ricerca rispetto alle altre parti.

Esempio: 

(or actors:'Alec Guinness' actors:'Harrison Ford' actors:'James Earl Jones')
phrase

Sintassi: (phrase field=FIELD boost=N 'STRING')

Cerca in un text-array campo text o la frase specificata. Se ometti l'fieldopzione, Amazon CloudSearch cerca tutti i text-array campi text e i campi configurati staticamente per impostazione predefinita. Per impostazione predefinita, i campi dinamici e i campi literal non sono oggetto di ricerca. Puoi specificare quali campi desideri cercare per impostazione predefinita specificando l'opzione. q.options fields

Utilizza l'operatore phrase per combinare una ricerca di periodo con altri criteri di ricerca in una query strutturata. Ad esempio q=(and (term field=title 'star') (range field=year {,2000])) restituisce tutti i documenti che contengono star nel campo del titolo e hanno valore minore o uguale a 2000 per l'anno.

Il valore boost è un valore numerico positivo che aumenta l'importanza di questa parte della query di ricerca rispetto alle altre parti.

Esempio: 

(phrase field=plot 'teenage girl')
prefix

Sintassi: (prefix field=FIELD boost=N 'STRING')

Cerca untext, text-arrayliteral, o literal-array campo per il prefisso specificato seguito da zero o più caratteri. Se ometti l'fieldopzione, Amazon CloudSearch cerca tutti i text-array campi text e i campi configurati staticamente per impostazione predefinita. Per impostazione predefinita, i campi dinamici e i campi literal non sono oggetto di ricerca. Puoi specificare quali campi desideri cercare per impostazione predefinita specificando l'opzione. q.options fields

Utilizza l'operatore prefix per combinare una ricerca di prefisso con altri criteri di ricerca in una query strutturata. Ad esempio, q=(and (prefix field=title 'sta') (range field=year {,2000])) restituisce tutti i documenti che contengono il prefisso sta nel campo del titolo e hanno valore minore o uguale a 2000 per l'anno.

Il valore boost è un valore numerico positivo che aumenta l'importanza di questa parte della query di ricerca rispetto alle altre parti.

Nota

Per implementare i suggerimenti di ricerca, è necessario configurare ed eseguire query su un suggeritore anziché eseguire ricerche di prefissi. Per ulteriori informazioni, consulta Richieste di suggerimento.

Esempio: 

(prefix field=title 'star')
range

Sintassi: (range field=FIELD boost=N RANGE)

Esegue la ricerca di un campo numerico (double, double-array, int, int-array) o di data (date, date-array) per i valori nell'intervallo specificato. Restituisce i documenti che presentano almeno un valore nel campo all'interno dell'intervallo specificato. È necessario specificare l'opzione field.

Utilizza l'operatore range per combinare una ricerca di intervallo con altri criteri di ricerca in una query strutturata. Ad esempio q=(and (term field=title 'star') (range field=year {,2000])) restituisce tutti i documenti che contengono star nel campo del titolo e hanno valore minore o uguale a 2000 per l'anno.

Per specificare un intervallo di valori, utilizza una virgola (,) per separare i limiti superiore e inferiore e inserisci l'intervallo tra parentesi tonde o parentesi graffe. Una parentesi quadra, [o], indica che il limite è incluso nell'intervallo, una parentesi graffa, {or}, esclude il limite. Puoi omettere il limite superiore o inferiore per specificare un intervallo aperto. Quando si omette un limite, è necessario utilizzare un tutore riccio.

Le date e gli orari sono specificati in UTC (Coordinated Universal Time) secondo IETF RFC3339:. yyyy-mm-ddTHH:mm:ss.SSSZ In UTC, ad esempio, le 17:00 del 23 agosto 1970 sono:. 1970-08-23T17:00:00Z Tieni presente che puoi anche specificare frazioni di secondo quando specifichi gli orari in UTC. Ad esempio, 1967-01-31T23:20:50.650Z.

Il valore boost è un valore numerico positivo che aumenta l'importanza di questa parte della query di ricerca rispetto alle altre parti.

Esempi: 

(range field=year [1990,2000])
(range field=year {,2000])
(range field=year [1990,})
term

Sintassi: (term field=FIELD boost=N 'STRING'|VALUE)

Cerca una stringa, un valore numerico o una data nel campo specificato. L'fieldopzione deve essere specificata durante la ricerca di un valore. Se ometti l'fieldopzione, Amazon CloudSearch cerca tutti i text-array campi text e i campi configurati staticamente per impostazione predefinita. Per impostazione predefinita, i campi dinamici e i campi literal non sono oggetto di ricerca. Puoi specificare quali campi desideri cercare per impostazione predefinita specificando l'opzione. q.options fields

Utilizza l'operatore term per combinare una ricerca di termine con altri criteri di ricerca in una query strutturata. Ad esempio, q=(and (term field=title 'star') (range field=year {,2000])) restituisce tutti i documenti che contengono star nel campo del titolo e hanno valore minore o uguale a 2000 per l'anno.

Le stringhe e le date devono essere racchiuse tra virgolette singole. Le virgolette singole o le barre rovesciate n una stringa devono essere precedute dal carattere di escape barra rovesciata.

Le date e gli orari sono specificati in UTC (Coordinated Universal Time) secondo IETF RFC3339:. yyyy-mm-ddTHH:mm:ss.SSSZ In UTC, ad esempio, le 17:00 del 23 agosto 1970 sono:. 1970-08-23T17:00:00Z Tieni presente che puoi anche specificare frazioni di secondo quando specifichi gli orari in UTC. Ad esempio, 1967-01-31T23:20:50.650Z.

Il valore boost è un valore numerico positivo che aumenta l'importanza di questa parte della query di ricerca rispetto alle altre parti.

Esempi: 

(term field=title 'star')
(term field=year 2000)

Sintassi di ricerca semplice

Utilizza la sintassi di ricerca CloudSearch semplice di Amazon per definire i criteri di ricerca quando usi il parser di simple query. Il parser di query semplice viene utilizzato per impostazione predefinita se non si specifica il parametro q.parser.

Questo tipo di parser di query consente di cercare singoli termini o periodi. Per impostazione predefinita, la ricerca viene eseguita in tutti i campi text e text-array configurati staticamente. Per impostazione predefinita, i campi dinamici e i campi literal non sono oggetto di ricerca. È possibile utilizzare il parametro q.options per specificare i campi in cui si desidera eseguire la ricerca, modificare l'operatore predefinito utilizzato per combinare singoli termini nella stringa di ricerca oppure disabilitare uno qualsiasi degli operatori di parser semplici (and, escape, fuzzy, near, not, or, phrase, precedence, prefix, whitespace).

Per ulteriori informazioni su come utilizzare i parser di query semplice, vedi text.

+ (and)

Sintassi: +TERM

Richiede il termine specificato. Per corrispondere, i documenti devono contenere il termine specificato.

Esempio: +star

\ (escape)

Sintassi: \CHAR

Aggiunge caratteri di escape ai caratteri speciali che si desidera cercare. Perché facciano parte della query, ai seguenti caratteri è necessario aggiungere caratteri di escape: + - & | ! ( ) { } [ ] ^ " ~ * ? : \ /.

Esempio: M\*A\*S\*H

~ (fuzzy)

Sintassi: TERM~N

Esegue una ricerca fuzzy. Aggiungere l'operatore ~ e un valore a un termine per indicare in che misura i termini possono differire ed essere considerati comunque una corrispondenza.

Esempio: stor~1

~ (near)

Sintassi: "PHRASE"~N

Esegue una ricerca di frasi simili. Aggiungere l'operatore ~ e un valore a un periodo per indicare quanto possono essere distanti tra loro i termini ed essere considerati comunque una corrispondenza per il periodo.

Esempio: "star wars"~4

- (not)

Sintassi: -TERM

Vieta il termine specificato. Per corrispondere, i documenti non devono contenere il termine specificato.

Esempio: star -wars

| (or)

Sintassi: |TERM

Rende opzionale il termine specificato.

Esempio: star |wars

"..." (phrase)

Sintassi: "PHRASE"

Esegue la ricerca dell'intero periodo. Può essere combinata con l'operatore ~ per eseguire una ricerca di frasi simili.

Esempio: "star wars"

(...) (precedence)

Sintassi: (...)

Controlla l'ordine in cui vengono valutati i vincoli di query. Nella valutazione ha la precedenza il contenuto delle parentesi più interne.

Esempio: +(war|trek)+star

* (prefix)

Sintassi: CHARS*

Restituisce i documenti che contengono i termini che includono il prefisso selezionato.

Esempio: sta*

Risposta della ricerca

Quando una richiesta riesce, il corpo della risposta contiene i risultati della ricerca. Per impostazione predefinita, i risultati della ricerca vengono restituiti in formato JSON. Se il parametro format è impostato su xml, i risultati della ricerca vengono restituiti in formato XML.

A meno che non si specifichi in modo esplicito il parametro return, per ogni documento corrispondente (occorrenza) sono inclusi l'ID documento e tutti i campi restituibili. La risposta mostra anche il numero totale di occorrenze trovate (found) e l'indice del primo documento elencato (start). Per impostazione predefinita, la risposta contiene le prime 10 occorrenze. È possibile specificare il parametro size nella richiesta per controllare la quantità di occorrenze incluse in ogni risposta. Per scorrere le occorrenze, è possibile utilizzare il parametro start o cursor. Per ulteriori informazioni, consulta Paginate the results.

Il seguente esempio mostra una tipica risposta in formato JSON:

{
    "status": {
        "rid": "rtKz7rkoeAojlvk=",
        "time-ms": 10
    },
    "hits": {
        "found": 3,
        "start": 0,
        "hit": [
            {
                "id": "tt1142977",
                "fields": {
                    "rating": "6.9",
                    "genres": [
                        "Animation",
                        "Comedy",
                        "Family",
                        "Horror",
                        "Sci-Fi"
                    ],
                    "plot": "Young Victor conducts a science experiment to  
                             bring his beloved dog Sparky back to life, only
                              to face unintended, sometimes monstrous, 
                              consequences.",
                    "release_date": "2012-09-20T00:00:00Z",
                    "title": "Frankenweenie",
                    "rank": "1462",
                    "running_time_secs": "5220",
                    "directors": [
                        "Tim Burton"
                    ],
                    "image_url": "http://ia.media-imdb.com/images/M/MV5BMjIx
                                  ODY3MjEwNV5BMl5BanBnXkFtZTcwOTMzNjc4Nw@@._
                                  V1_SX400_.jpg",
                    "year": "2012",
                    "actors": [
                        "Winona Ryder",
                        "Catherine O'Hara",
                        "Martin Short"
                    ]
                }
            },
			.
			.
			.
        ]			
    }
}

L'esempio seguente mostra la risposta XML equivalente.

<results>
    <status rid="itzL7rkoeQojlvk=" time-ms="34"/>
    <hits found="3" start="0">
        <hit id="tt1142977">
            <field name="rating">6.9</field>
            <field name="genres">Animation</field>
            <field name="genres">Comedy</field>
            <field name="genres">Family</field>
            <field name="genres">Horror</field>
            <field name="genres">Sci-Fi</field>
            <field name="plot">Young Victor conducts a science experiment to
                               bring his beloved dog Sparky back to life, only
                               to face unintended, sometimes monstrous, 
                               consequences.
            </field>
            <field name="release_date">2012-09-20T00:00:00Z</field>
            <field name="title">Frankenweenie</field>
            <field name="rank">1462</field>
            <field name="running_time_secs">5220</field>
            <field name="directors">Tim Burton</field>
            <field name="image_url">http://ia.media-imdb.com/images/M/MV5BMjI
                                    xODY3MjEwNV5BMl5BanBnXkFtZTcwOTMzNjc4Nw@@.
                                    _V1_SX400_.jpg
            </field>
            <field name="year">2012</field>
            <field name="actors">Winona Ryder</field>
            <field name="actors">Catherine O'Hara</field>
            <field name="actors">Martin Short</field>
        </hit>
        .
        .
        .
    </hits>
</results>

L'impostazione del formato della risposta interessa solo le risposte alle richieste riuscite. Il formato di una risposta di errore dipende dall'origine dell'errore. Gli errori restituiti dal servizio di ricerca vengono sempre restituiti in JSON. Gli errori 5xx dovuti a timeout del server e ad altri problemi di routing delle richieste vengono restituiti in XML. Quando una richiesta restituisce un codice di errore, il corpo della risposta contiene informazioni sull'errore che si è verificato. Se si verifica un errore durante l'analisi e la convalida del corpo della richiesta, il codice di errore viene impostato su 400 e il corpo della risposta include un elenco degli errori e del luogo in cui si sono verificati.

Intestazioni delle risposte di ricerca

Content-Type

Tipo MIME standard che descrive il formato dei dati oggetto. Per ulteriori informazioni, consultare la sezione 14 del protocollo RFC 2616 di W3C.

Valori validi: application/json o application/xml

Impostazione predefinita: application/json

Content-Length

La lunghezza in byte del corpo della risposta.

Proprietà della risposta della ricerca (JSON)

status

Contiene l'id di risorsa (rid) e il tempo impiegato per elaborare la richiesta (time-ms).

rid

L'ID di risorsa crittografato.

time-ms

Il tempo impiegato per elaborare la richiesta di ricerca in millisecondi.

hits

Contiene il numero di documenti corrispondenti (found), l'indice del primo documento incluso nella risposta (start) e una serie (hit) che elenca gli ID di documento e i dati per ogni occorrenza.

found

Il numero totale di risultati che corrispondono alla richiesta di ricerca dopo che Amazon CloudSearch ha terminato l'elaborazione della richiesta.

start

L'indice della prima occorrenza restituita in questa risposta.

hit

Serie che elenca gli ID di documento e i dati per ogni occorrenza.

id

L'identificatore univoco per un documento.

fields

Elenco di campi restituiti.

facets

Contiene i conteggi dei facet e le relative informazioni.

FACETFIELD

Campo per il quale sono stati calcolati i facet.

buckets

Serie di valori e conteggi di facet.

value

Il valore del facet conteggiato.

count

Il numero di occorrenze che contengono il valore del facet in FACETFIELD.

Elementi della risposta di ricerca (XML)

results

Contiene i risultati di ricerca. Qualsiasi errore che si verifichi durante l'elaborazione della richiesta viene restituito come messaggio nell'elemento delle informazioni.

status

Contiene l'id di risorsa (rid) e il tempo impiegato per elaborare la richiesta (time-ms).

hits

Contiene le statistiche delle occorrenze e una raccolta di elementi occorrenza. L'attributo found è il numero totale di risultati che corrispondono alla richiesta di ricerca dopo che Amazon CloudSearch ha terminato l'elaborazione dei risultati. Gli elementi occorrenza vengono ordinati in base al relativo punteggio di rilevanza o all'opzione sort specificata nella richiesta di ricerca.

hit

Documento che corrisponde alla richiesta di ricerca. L'attributo id è l'id univoco del documento. Contiene un elemento d (dati) per ciascun campo restituito.

field

Un campo restituito da un'occorrenza. Gli elementi occorrenza d (dati) per ciascun campo restituito.

facets

Contiene un elemento facet per ogni facet richiesto nella richiesta di ricerca.

facet

Contiene un elemento bucket per ciascun valore di un campo per il quale è stato calcolato un conteggio di facet. È possibile utilizzare l'opzione di dimensione facet.FIELD per specificare il numero di vincoli da restituire. Per impostazione predefinita, i conteggi dei facet vengono restituiti per i primi 10 vincoli. L'opzione dei bucket facet.FIELD consente di specificare esplicitamente i valori da contare.

bucket

Valore di un campo facet e il numero di occorrenze (conteggio) di tale valore all'interno delle occorrenze di ricerca.

Invio di richieste di suggerimenti in Amazon CloudSearch

È possibile inviare le richieste tramite HTTP GET all'endpoint di ricerca del tuo dominio in 2013-01-01/suggest. Per informazioni su come controllare l'accesso al servizio di suggerimenti, vedi configure access policies.

In tutte le richieste di suggerimento è necessario specificare la versione API e indicare che deve corrispondere alla versione API specificata al momento della creazione del dominio.

Ad esempio, la seguente richiesta ottiene suggerimenti dal dominio search-movies-rr2f34ofg56xneuemujamut52i.us-east-1.cloudsearch.amazonaws.com per la stringa di query oce utilizzando il suggeritore denominato title. 

http://search-imdb-hd6ebyouhw2lczkueyuqksnuzu.us-west-2.cloudsearch.amazonaws.com/2013-01-01/suggest -d"q=oce&suggester=suggest_title"

Puoi utilizzare qualsiasi metodo desideri per inviare richieste GET all'endpoint di ricerca del tuo dominio: puoi inserire l'URL della richiesta direttamente in un browser Web, utilizzare cURL per inviare la richiesta o generare una chiamata HTTP utilizzando la tua libreria HTTP preferita. Puoi anche utilizzare Search Tester nella CloudSearch console Amazon per ricevere suggerimenti. Per ulteriori informazioni, consulta Ricerca con il test di ricerca.

Importante

Gli endpoint di ricerca e il documento di un dominio rimangono invariati per tutta la durata del dominio. Dovresti memorizzare gli endpoint nella cache invece di recuperarli prima di ciascuna richiesta di ricerca o caricamento. È probabile che interrogare il servizio di CloudSearch configurazione Amazon chiamando aws cloudsearch describe-domains o DescribeDomains prima di ogni richiesta comporti una limitazione delle richieste.

Per impostazione predefinita, Amazon CloudSearch restituisce la risposta in JSON. Puoi ottenere i risultati in formato XML specificando il parametro format, format=xml. L'impostazione del formato della risposta interessa solo le risposte alle richieste riuscite. Il formato di una risposta di errore dipende dall'origine dell'errore. Gli errori restituiti dal servizio di ricerca vengono sempre restituiti in JSON. Gli errori 5xx dovuti a timeout del server e ad altri problemi di routing delle richieste vengono restituiti in XML.

Suggerimento

Richieste di suggerimento

Suggerisci la sintassi in Amazon CloudSearch

GET /2013-01-01/suggest

Suggerisci intestazioni di richiesta in Amazon CloudSearch

HOST

L'endpoint delle richieste di ricerca per il dominio sottoposto a query. Puoi utilizzare DescribeDomains per recuperare l'endpoint delle richieste di ricerca del dominio.

Campo obbligatorio: sì

Suggerisci parametri di richiesta in Amazon CloudSearch

q

La stringa per la quale ottenere i suggerimenti.

Tipo: stringa

Campo obbligatorio: sì

suggester

Il nome del suggeritore da utilizzare per trovare le corrispondenze suggerite.

Tipo: stringa

Campo obbligatorio: sì

size

Il numero massimo di suggerimenti da restituire.

Tipo: numero intero positivo

Impostazione predefinita: 10

Campo obbligatorio: no

format

Specifica il tipo di contenuti della risposta.

Tipo: stringa

Valori validi: json|xml

Impostazione predefinita: json

Campo obbligatorio: no

Risposta del suggerimento

Quando una richiesta riesce, il corpo della risposta contiene i suggerimenti. Per impostazione predefinita, i suggerimenti vengono restituiti in formato JSON. Puoi ottenere i risultati in formato XML impostando il parametro format su xml.

L'impostazione del formato della risposta interessa solo le risposte alle richieste riuscite. Il formato di una risposta di errore dipende dall'origine dell'errore. Gli errori restituiti dal servizio di ricerca vengono sempre restituiti in JSON. Gli errori 5xx dovuti a timeout del server e ad altri problemi di routing delle richieste vengono restituiti in XML. Quando una richiesta restituisce un codice di errore, il corpo della risposta contiene informazioni sull'errore che si è verificato. Se si verifica un errore durante l'analisi e la convalida del corpo della richiesta, il codice di errore viene impostato su 400 e il corpo della risposta include un elenco degli errori e del luogo in cui si sono verificati.

L'esempio seguente mostra una risposta in formato JSON a una richiesta di suggerimenti.

{
   "status": {
      "rid": "qOSM5s0oCwr8pVk=",
      "time-ms": 2
   },
   "suggest": {
      "query": "oce",
      "found": 3,
      "suggestions": [
         {
          "suggestion": "Ocean's Eleven",
           "score": 0,
           "id": "tt0054135"
         },
         {
          "suggestion": "Ocean's Thirteen",
          "score": 0,
          "id": "tt0496806"
         },
         {
          "suggestion": "Ocean's Twelve",
          "score": 0,
          "id": "tt0349903"
         }
      ]
   }
}

L'esempio seguente mostra la risposta XML equivalente:

<results>
   <status rid="/pSz580oDQr8pVk=" time-ms="2"/>
   <suggest query="oce" found="3">
      <suggestions>
         <item suggestion="Ocean's Eleven" score="0" id="tt0054135"/>
         <item suggestion="Ocean's Thirteen" score="0" id="tt0496806"/>
         <item suggestion="Ocean's Twelve" score="0" id="tt0349903"/>
      </suggestions>
   </suggest>
</results>

Errori dei servizi di ricerca

Una richiesta di ricerca o suggerimenti può restituire tre tipi di codici di stato:

  • I codici di stato 5xx indicano che si è verificato un errore interno del server. È consigliabile intercettare e riprovare tutti i codici di errore 5xx in quanto generalmente rappresentano condizioni di errore transitorie. Per ulteriori informazioni, consulta Gestione degli errori.

  • I codici di stato 4xx indicano che la richiesta non è stata formulata correttamente. Correggi gli errori riportati prima di inviare nuovamente la tua richiesta.

  • I codici di stato 2xx indicano che la richiesta è riuscita.

Il formato di una risposta di errore dipende dall'origine dell'errore. Gli errori restituiti dal servizio di ricerca vengono sempre restituiti in JSON. Gli errori 5xx dovuti a timeout del server e ad altri problemi di routing delle richieste vengono restituiti in XML.

Gli errori restituiti dal servizio di ricerca contengono le informazioni seguenti:

error

Contiene un messaggio di errore restituito dal servizio di ricerca. Per ogni errore sono incluse le proprietà code e msg.

code

Il codice di errore.

msg

Una descrizione dell'errore restituita dal servizio di ricerca.