Come impostare i parametri della query

Imparare i fondamenti del lavoro con i parametri di query nelle funzioni del connettore HTTP, in conformità con la documentazione API.

I parametri di query consentono di affinare e personalizzare i risultati di una funzione Connector. Utilizzate i parametri per ordinare, filtrare, impostare limiti, compensare un indice e altro ancora. Questo articolo utilizza i parametri dell'API Tulip Table, ma altre API possono avere requisiti diversi. Assicurarsi di controllare la documentazione per assicurarsi di utilizzare la sintassi e le specifiche corrette.

Interrogazione con i filtri

I filtri possono essere molto utili per estrarre solo i dati che interessano. La sintassi di questi filtri può essere a volte un po' complicata. Di seguito viene illustrato il modo in cui ciascuno di essi è formato nell'esempio di una richiesta GET di record, seguito da un esempio completo.

Inomi dei campi personalizzati sono sempre preceduti da un identificatore a cinque cifre. Questi possono essere trovati più facilmente dopo una richiesta GET all per verificare il vero nome del campo.

• Es. "campo"="maytq_scrap_count"

I valoridegli argomenti sono spesso semplici. Se si tratta di un valore di testo, assicurarsi di metterlo tra virgolette.

• Es. "arg":15

Abbinare il tipo di funzione che si desidera utilizzare.

• Es. "functionType": "greaterThan".

Una richiesta completa potrebbe essere simile a questa:

https://brian.tulip.co/api/v3/tables/W2HPvyCZrjMMHTiip/records?limit=100&sortBy=\\\code(01)019&sortDir=asc&filters=[{"field": "maytq_scrap\_count", "arg":15, "functionType": "greaterThan"}]&filterAggregator=any

Come trovare i parametri di query nella documentazione

Per individuare i parametri di query disponibili per la richiesta, consultare la documentazione dell'API. Se si utilizza l'API Tulip Table, la documentazione si trova all'indirizzo: your-instance.tulip.co/apiDocs. Selezionare la richiesta che si desidera utilizzare e scorrere fino alla scheda Parameters.

Ogni singolo metodo ha i propri parametri, ma non tutte le richieste hanno parametri associati. Assicurarsi di prendere nota di quelli disponibili nella documentazione.

Sintassi dei parametri delle query

La sintassi dei parametri delle query si basa su un formato di stringa di query. Questo formato assegna valori ai parametri specificati, con la stringa di query stessa che fa parte dell'URL.

Nell'Editor funzioni del connettore, fare clic su Aggiungi parametro per creare un nuovo parametro di query.

Un parametro di query è composto da due parti: una chiave e un valore. La chiave è il nome del parametro e il valore è l'informazione che imposta il parametro per i risultati.

La sintassi dei parametri di query utilizza Dot Notation, che specifica il tipo esatto di parametro. Assicurarsi che il caso di scrittura corrisponda allo standard API dell'altro sistema.

Applicare parametri comuni alle funzioni del connettore

Per impostare un parametro alla funzione del connettore, occorre innanzitutto identificare il parametro che si desidera utilizzare nella documentazione dell'API. I parametri hanno requisiti diversi per ciascuno di essi, quindi vediamo come si presentano.

:::(Info) (NOTA) Per continuità, useremo la stessa richiesta API Call in tutti gli esempi che seguono. Questa è la richiesta GET che recupera un elenco di record in una tabella Tulip tramite l'API Tulip Table. Altre API utilizzate avranno specifiche diverse per i parametri; assicurarsi di consultare i requisiti della documentazione dell'API. :::

Limiti

I limiti impostano un limite massimo per i risultati restituiti. Si noti che alcuni limiti hanno impostazioni predefinite, quindi è bene controllare la documentazione dell'API per capire il valore iniziale.

EsempioVogliamo ottenere non più di 70 record quando viene eseguita la funzione connettore. Fortunatamente, il valore predefinito per il limite in questa richiesta è 10 e quello massimo è 100. La sintassi del parametro della query dovrebbe essere la seguente:

Filtri

I filtri separano e raffinano i risultati in base alle informazioni fornite dal parametro.

I filtri hanno tre parti, che devono essere scritte nei singoli parametri:

• Campo - il nome della colonna della tabella
• Tipo di funzione - il tipo di funzione di confronto
• Argomento - il valore con cui confrontare i risultati.

Ogni filtro ha 3 parti e ogni filtro completo è un Oggetto. Utilizzando la notazione a punti per scrivere ogni chiave, specificare il tipo di parametro ('filtro'), il numero del filtro (da 0 a n) e la parte del filtro ('campo', 'functionType' o 'arg'). Deve esserci un parametro per tutte e tre le parti del filtro.

EsempioVogliamo assicurarci che i risultati della funzione connettore mostrino solo i valori di un campo specifico (eubmc_value) che sia uguale al valore di input specificato (consumable) della funzione. Poiché questo è il nostro primo filtro nei parametri della funzione, il numero del filtro è 0. Ciò significa che ogni chiave per questo filtro inizierà con "filtro.0". La sintassi di questo filtro dovrebbe essere la seguente:

Ordinamento

L'ordinamento dei risultati dà priorità alla vista in base alle informazioni del parametro. I risultati ordinati determinano quali sono inclusi nelle aggregazioni. Si possono avere più funzioni di ordinamento, ma l'ordine delle opzioni determina la priorità dell'ordinamento.

Le funzioni di ordinamento hanno due parti:

• sortBy - il campo per il quale si desidera ordinare i risultati
• sortDir - la direzione dell'ordinamento, ascendente (asc) o discendente (desc).

Ogni funzione di ordinamento ha 3 parti. Utilizzando la notazione a punti per scrivere ogni chiave, specificare il tipo di parametro ('sortOptions'), il numero di ordinamento (da 0 a n) e l'argomento di ordinamento ('sortBy' o 'sortDir'). Affinché la funzione di ordinamento funzioni, deve essere presente un parametro per tutte e tre le parti.

EsempioVogliamo che i risultati della funzione connettore siano ordinati in base al campo aggiornato più di recente, in ordine crescente. Poiché questa è la prima funzione di ordinamento, il numero di ordinamento è 0. Ciò significa che entrambe le chiavi di questo ordinamento inizieranno con "sortOptions.0". Per la chiave sortBy, il valore è un valore speciale ('_updatedAt') derivato dalla documentazione dell'API per ordinare i campi aggiornati. La sintassi di questi parametri dovrebbe essere la seguente:

Offset

Gli offset determinano l'indice di partenza del risultato restituito. Questo parametro è usato per la paginazione, non per l'ordine dei record che è determinato dai parametri di ordinamento. Il valore del parametro deve essere un intero maggiore o uguale a 0.

EsempioVogliamo visualizzare solo i record dopo la quinta posizione, in modo da non vedere i primi 5 risultati. La sintassi del parametro di query dovrebbe essere la seguente:

Aggregatori di filtri

Gli aggregatori di filtri determinano il modo in cui i filtri dei parametri vengono combinati. I due valori tra cui scegliere sono "any" e "all". Il valore "all" significa che tutti i filtri devono avere un record per poterlo includere nei risultati. Il valore "any" significa che almeno uno dei filtri deve corrispondere a un record per essere incluso nei risultati. Il valore predefinito è "tutti", indipendentemente dall'impostazione del parametro.

EsempioAbbiamo una serie di filtri nei parametri della query, ma abbiamo bisogno che solo uno di questi filtri sia vero per far sì che i record corrispondano alla nostra richiesta. La sintassi del parametro di query dovrebbe essere la seguente:

Filtri multipli

In alcuni casi, si possono avere più filtri da controllare nella tabella. In questo caso, si possono aggiungere più filtri all'oggetto filters. L'aspetto potrebbe essere il seguente

filters=[{"campo": "maytq_scrap\_count", "arg":15, "functionType": "greaterThan"},{"campo": "maytq\_scrap\_reason", "arg": "scratch", "functionType": "equal"}]

Ulteriori letture

• Panoramica dei connettori HTTP
• Come creare e configurare una funzione del connettore HTTP
• Come usare l'API delle tabelle