Riferimento alla query di filtro

Modifica online

L'API REST del servizio di assistente AI offre potenti funzionalità di ricerca nei log tramite query di filtro. È possibile utilizzare il parametro filter API ` /logsv2 ` per cercare nel registro della skill gli eventi che corrispondono a una query specificata.

Il parametro 'filter è una query memorizzabile nella cache che limita i risultati agli elementi che corrispondono al filtro specificato. Puoi applicare un filtro su diversi oggetti che fanno parte del modello di risposta JSON (ad esempio, il testo dell'input utente, gli intenti e le entità rilevati o il punteggio di affidabilità).

Per vedere esempi di query di filtro, vedere Esempi.

Per ulteriori informazioni sul metodo /logsGET e sul relativo modello di risposta, consultare la Documentazione dell'API.

Sintassi della query di filtro

Il seguente esempio mostra il formato generale di una query di filtro:


Ubicazione	Operatore di query	Termine
`request.input.text`	`::`	`"IBM Watson"`

Il campo _location_ indica il campo su cui si desidera applicare il filtro (in questo esempio request.input.text).
L'_operatore di query_, che specifica il tipo di corrispondenza che si desidera utilizzare (corrispondenza approssimativa o corrispondenza esatta).
Il _termine_ indica l'espressione o il valore che si desidera utilizzare per valutare il campo ai fini della corrispondenza. Il termine può contenere testo letterale e operatori, come descritto nella sezione seguente.

Il filtraggio per intento o entità richiede una sintassi leggermente diversa dal filtraggio su altri campi. Per ulteriori informazioni, vedere Filtraggio per intento o entità.

Nota: la sintassi delle query di filtro utilizza alcuni caratteri che non sono ammessi nelle query HTTP. Assicurati che tutti i caratteri speciali, inclusi spazi e virgolette, siano codificati tramite URL quando inviati come parte di una query HTTP. Ad esempio, il filtro " response_timestamp<2020-01-01 può essere specificato come " response_timestamp%3C2020-01-01.

Operatori

Nella query di filtro puoi utilizzare i seguenti operatori.


Operatore	Descrizione
`:`	Operatore di query di corrispondenza fuzzy. Aggiungi il prefisso `:` al termine di query se vuoi trovare una corrispondenza con qualsiasi valore che contenga il termine di query o una variante grammaticale del termine di query. La corrispondenza fuzzy è disponibile per i valori di testo e di entità immessi dall'utente.
`::`	Operatore di query di corrispondenza esatta. Aggiungi il prefisso `::` se vuoi trovare una corrispondenza solo con i valori esattamente uguali al termine di query.
`:!`	Operatore di query di corrispondenza fuzzy negativa. Anteponi il termine di ricerca a `:!` se desideri trovare solo i valori che _non_ contengono il termine di ricerca o una sua variante grammaticale.
`::!`	Operatore di query di corrispondenza esatta negativa. Aggiungi il prefisso al termine di `::!` ricerca se desideri trovare solo i valori che _non_ corrispondono esattamente al termine di ricerca.
`<=`, `>=`, `>`, `<`	Operatori di confronto. Aggiungi questi operatori come prefisso per il termine di query per trovare una corrispondenza in base al confronto aritmetico.
`\`	Operatore di escape. Da utilizzare nelle query che includono caratteri di controllo che altrimenti verrebbero analizzati come operatori. Ad esempio, `\!hello` corrisponderebbe al testo `!hello`.
`""`	Frase letterale. Utilizzare per racchiudere un termine di query che contiene spazi o altri caratteri speciali. Nessun carattere speciale all'interno delle virgolette viene analizzato dall'API.
`~`	Corrispondenza approssimativa. Aggiungi questo operatore seguito da `1` o `2` alla fine del termine di query per specificare il numero consentito di differenze a carattere singolo tra la stringa di query e una corrispondenza nell'oggetto di risposta. Ad esempio, `car~1` può corrispondere a `car`, `cat` o `cars`, ma non può corrispondere a `cats`. Questo operatore non è valido quando si filtra su '`log_id` o su qualsiasi campo data o ora, o con la corrispondenza fuzzy.
`*`	Operatore carattere jolly. Corrisponde a qualsiasi sequenza di zero o più caratteri. Questo operatore non è valido quando si filtra su '`log_id`, '`language`, '`request.context.system.assistant_id`, '`workspace_id`, '`request.context.metadata.deployment`, o su qualsiasi campo data o ora.
`()`, `[]`	Operatori di raggruppamento. Si usa per racchiudere un raggruppamento logico di espressioni multiple utilizzando gli operatori booleani.
\|	Operatore booleano _or_.
`,`	Operatore booleano _and_.

Filtro per intento o entità

A causa delle differenze nel modo in cui gli intenti e le entità sono memorizzati internamente, la sintassi per filtrare su un intento o un'entità specifica è diversa da quella utilizzata per altri campi nel JSON restituito. Per specificare un campo intent o entity in una raccolta di intents o entities, devi utilizzare l'operatore di corrispondenza : al posto di un punto.

Ad esempio, questa query corrisponde a qualsiasi evento registrato in cui la risposta include un intento rilevato denominato hello:

response.output.intents:intent::hello

Nota l'operatore : al posto di un punto (intents:intent)

Utilizza lo stesso modello per la corrispondenza su qualsiasi campo di un intento o entità rilevato nella risposta. Ad esempio, questa query corrisponde a qualsiasi evento registrato in cui la risposta include un'entità rilevata con il valore soda:

response.output.entities:value::soda

Allo stesso modo, si possono filtrare gli intenti o le entità che vengono inviati come parte della richiesta, come in questo esempio:

request.input.intents:intent::hello

Filtro per altri campi

Per filtrare su un altro campo dei dati di log, specificare la posizione come percorso che identifica i livelli di oggetti annidati nella risposta JSON dell'API /logs. Utilizza i punti (.) per specificare i livelli successivi di nidificazione nei dati JSON. Ad esempio, la posizione " request.input.text identifica il campo di testo dell'utente, come mostrato nel seguente frammento JSON:

  "request": {
    "input": {
      "text": "Good morning"
    }
  }

Il filtraggio non è disponibile per tutti i campi. Puoi applicare il filtro ai seguenti campi:

assistant_id
customer_id
language
request.context.global.system.user_id
request.input.text
request_timestamp
response.context.global.system.user_id
response.output.entities
response.output.intents
response_timestamp
session_id
skill_id
snapshot

L'applicazione del filtro su altri campi non è attualmente supportata.

Esempi

Gli esempi seguenti illustrano vari tipi di query utilizzando questa sintassi.


Descrizione	Interroga
La data della risposta è nel mese di luglio 2020.	`response_timestamp>=2020-07-01,response_timestamp<2020-08-01`
La data/ora della risposta è precedente a `2019-11-01T04:00:00.000Z`.	`response_timestamp<2019-11-01T04:00:00.000Z`
Il messaggio viene etichettato con l'ID cliente `my_id`.	`customer_id::my_id`
Il messaggio è stato inviato a un assistente AI specifico.	`assistant_id::dcd5c5ad-f3a1-4345-89c5-708b0b5ff4f7`
Il testo dell'input utente contiene la parola "order" o una variante grammaticale (ad esempio, `orders` o `ordering`.	`request.input.text:order`
Un nome intento nella risposta corrisponde esattamente a `place_order`.	`response.output.intents:intent::place_order`
Un nome entità nella risposta corrisponde esattamente a `beverage`.	`response.output.entities:entity::beverage`
Nessun nome di intento nella risposta corrisponde esattamente a '`order`.	`response.intents:intent::!order`
Il testo dell'input utente non contiene la parola "order" o una variante grammaticale.	`request.input.text:!order`
Il testo dell'input utente contiene la stringa `!hello`.	`request.input.text:\!hello`
Il testo dell'input utente contiene la stringa `IBM Watson`.	`request.input.text:"IBM Watson"`
Il testo dell'input utente contiene una stringa che non ha più di 2 differenze a carattere singolo rispetto a `Watson`.	`request.input.text:Watson~2`
Il testo inserito dall'utente contiene una stringa composta da '`comm`, seguito da zero o più caratteri, seguito da '`s`.	`request.input.text:comm*s`
Un nome intento nella risposta corrisponde esattamente a `hello` o a `goodbye`.	response.output.intents:intent:: (ciao\|arrivederci)
Un nome intento nella risposta corrisponde esattamente a `order` e un nome entità nella risposta corrisponde esattamente a `beverage`.	`[response.output.intents:intent::order,response.output.entities:entity::beverage]`

Filtro dei log v1

Se l'applicazione utilizza ancora l'API v1, è possibile interrogare e filtrare i log utilizzando il metodo v1 /logs. La sintassi del filtro è la stessa, ma la struttura dei log e delle richieste di messaggi v1 è diversa. Per ulteriori informazioni, consultare la Guida di riferimento alle API.

Con l'API /logs v1, puoi applicare il filtro sui seguenti campi:

language
meta.message.entities_count
request.context.metadata.deployment
request.context.system.assistant_id
request.input.text
response.context.conversation_id
response.entities
response.input.text
response.intents
response.top_intent
workspace_id

L'applicazione del filtro su altri campi non è attualmente supportata.