API GW Apps Records

Panoramica dell'API Records

L'API Records è un'API REST accessibile tramite chiamate HTTP esplicite; l'API espone la maggior parte delle funzionalità relative ai record disponibili nell'interfaccia web GW Apps. Questo documento descrive come utilizzare le chiamate RESTful.

Nota: l'API non supporta chiamate che modificano il design o la configurazione dell'applicazione.

Nota: questa documentazione API ha lo scopo di fornire al lettore una panoramica delle funzionalità delle API e delle modalità di accesso alle stesse. Quando si tenta di scrivere chiamate API, si consiglia vivamente di utilizzare la documentazione API direttamente associata alla chiave API specifica che si intende chiamare. Tale documentazione include esempi con gli ID effettivi del modulo e degli elementi del modulo, esempi per ciascun campo disponibile nei moduli associati, ecc. Ciò consentirà di copiare e incollare direttamente i frammenti di codice dalla documentazione al proprio codice. Se si desidera utilizzare gli esempi presenti in questa documentazione, è necessario modificarli in base ai campi, all'ID del modulo, ecc.

Autenticazione

Prima che la tua applicazione possa accedere all'endpoint per ottenere dati privati, deve ottenere unaccess_tokenche conceda l'accesso a tale API. Un singoloaccess_tokenpuò concedere diversi livelli di accesso a più API.

In genere, è buona norma richiedere solo gli ambiti necessari. Ad esempio, un'app che desidera accedere alla ricerca delle entità disponibili dovrebbe abilitare solo gli ambiti "Visualizza e cerca". È sempre possibile modificare l'accesso all'ambito ogni volta che cambia il caso d'uso o generare altre chiavi per altri scopi.

Dopo che un'applicazione ha ottenuto un token di accesso, lo invia a un'API GW Apps nell'intestazione di una richiesta di autorizzazione HTTP. I token di accesso sono validi solo per l'insieme di operazioni e risorse descritte nell'ambito della chiave API creata.

Ad esempio, se viene emesso un token di accesso per il Modulo A, esso non garantisce l'accesso all'API dei record del Modulo B.

Autenticazione

La tua applicazione deve utilizzare questa API "/token" per autorizzare le richieste. Ogni access_token generato è valido per 1 ora.

Richiesta HTTP

POSThttps://api.gwapps.com/v1/token

Intestazioni della richiesta

Intestazione	valore
Tipo di contenuto	applicazione/json

Corpo della richiesta

Parametro	Descrizione	Tipo
Parametri corporei richiesti
chiave	La chiave generata da GWAPPS	stringa
e-mail	L'indirizzo e-mail da utilizzare per impersonare l'account utente per effettuare le chiamate API.	stringa
ID cliente	Il codice cliente citen_e0b70	stringa

Esempio di richiesta

  {
      "key": apiKey,
      "email": email,
      "customerId": "citen_e0b70"
  }

Risposta

inizio

Nota: il token generatoè valido per 1 ora, potrebbe essere necessario implementare una strategia per generare un nuovoaccess_tokendi conseguenza.

  {
      "access_token": access_token,
      "expires_in": 3600,
      "token_type": "Bearer"
  }

inizio

Nota: ogni richiesta inviata dall'applicazione all'API Records deve includere un token di autorizzazione. Il token identifica anche l'account utente che si desidera impersonare (che definisce il livello di accesso ai record specificati).

Intestazione	valore
Autorizzazione	Beareraccess_token
Tipo di contenuto	Applicazione/json

Filtri

I filtri e gli operatori supportati durante la ricerca di record utilizzando l'API "Cerca record".

Riferimento

Operatore	Campi supportati	Tipo di valore	Esempio di valore
BIANCO	Tutti i campi	Nessun valore richiesto
NOT_BLANK	Tutti i campi	Nessun valore richiesto
EQUALSNOT_EQUALS	Creato il, Aggiornato il	stringa	"16/11/2023, ore 03:30:00"
	Valuta, Numero	numero	100
	Data	stringa	"16 novembre 2023"
	E-mail	stringa	"john.doe@example.com"
	Numero di telefono	stringa	“3103101234”
	ID record	stringa	"REQ#00001"
	Paese, Stato, Testo, Area di testo	stringa	"Stati Uniti", "CA", "John"
	Tempo	stringa	«17:30»
EQUALS_VALUE	Casella di controllo, pulsante di opzione, menu a discesa, ricerca	stringa	"Opzione 1"
VALORE_DIFFERENTE
CONTIENE NON CONTIENE	Creato da, Aggiornato da, Utente, Elenco utenti	stringa	"Jane"
	E-mail	stringa	"jane.doe"
	Paese, Stato, Testo, Area di testo	stringa	"United", "John"
	ID record	stringa	"REQ#"
MAGGIORE_DI_MINORE_DI	Creato il, Aggiornato il	stringa	"16/11/2023, ore 03:30:00"
	Valuta, Numero	numero	100
	Data	stringa	"16 novembre 2023"
	Tempo	stringa	«17:30»
MAGGIORE_DI_UGUALE_A_MINORE_DI_UGUALE_A	Valuta, Numero	numero	100
MI PIACE_NON MI PIACE	Paese, Stato, Numero di telefono	stringa	"United", "310310"
LIKE_VALUE NOT_LIKE_VALUE	Casella di controllo, pulsante di opzione, menu a discesa, campo di ricerca	stringa	"Opzione 1"
IN	Palcoscenico	stringa [ ]	[“stg0”]

Note:

• Le date sono espresse in UTC
• Il formato accettato per la data è aaaa-MM-gg.
• Il formato accettato per la data e l'ora è aaaa-MM-ggTHH:mm:ss.
• Il formato dell'ora accettato è quello di 24 ore, ad esempio 13:30.
• Il formato accettato per il numero di telefono non contiene il codice del Paese, ad esempio 3236397888.

Filtri con condizione OR

I record verranno restituiti in base ai criteri se almeno una delle condizioni è vera.

{
  "filters": [
    [
      {
        "fieldCode": "company1",
        "operator": "CONTAINS",
        "value": "vip"
      },
      {
        "fieldCode": "name1",
        "operator": "CONTAINS",
        "value": "john"
      }
    ]
  ]
}

Filtri con condizione AND

I record verranno restituiti in base ai criteri se tutte le condizioni sono vere.

{
  "filters": [
    {
      "fieldCode": "company1",
      "operator": "EQUALS",
      "value": "Vipe"
    },
    {
      "fieldCode": "stage",
      "operator": "IN",
      "value": [
        "stg0"
      ]
    }
  ]
}

Dopo aver inserito il nome della nuova chiave API, aver aggiunto eventualmente una descrizione e aver cliccato su "Crea", vedrai l'Editor chiave API con la tua nuova chiave caricata, in modo da poter completare la sua configurazione:

Metodi API

Tutti i tipi di campo

Parametri

Parametro	Valore	Descrizione
formId	?????????????????????????	L'identificatore del modulo attualmente selezionato; questo valore è richiesto come parametro di query su ciascun endpoint.

Fasi

Tutti i record hanno un attributo stage che definisce lo stato del record. Il campo "All Field Types" ha le seguenti fasi definite, è necessario fare riferimento al stage.id per la creazione e l'aggiornamento dei record.

Stato / Nome d'arte	ID palco
Bozza	stg0
Pubblicato	stg1

Esempio di richiesta

  {
      "stage": "stg0"
  }

Oppure

  {
      "stage": {
        "id": "stg0"
        "status": "Draft"
      }
  }

Definizione record per il modulo "Tutti i tipi di campo"

Questa è la rappresentazione del record che include tutti i campi e i tipi di valori previsti.

Codice breve	Nome campo	Tipo	Valori accettati
campo_testo1	Testo	Testo	stringa
campo_data2	Data	Data	ISODate
utente1	Utente	Ricerca nella rubrica	{ “_id”: “string”, “name”: “string”, “email”: “string” }
menu a tendina1	Ricerca a tendina	Elenco	{ “code”: “string”, “value”: “string” }
area_testo1	Area di testo	Area di testo	stringa
ora1	Tempo	Tempo	stringa
elenco_utenti1	Elenco utenti	Elenco directory	[ { “_id”: “string”, “name”: “string”, “email”: “string” } ]
ricerca2	Ricerca	Ricerca multipla	{ “code”: “string”, “value”: “string” }
campo_numero1	Numero	Numero	numero
pulsante_radio1	Pulsante radio	Radio	{ “code”: “string”, “value”: “string” }
dipartimento1	Dipartimento	Testo	stringa
casella di controllo 1	Casella di controllo	Casella di controllo	[ { “code”: “string”, “value”: “string” } ]
telefono1	Telefono	Numero di telefono	{ “code”: “string”, “phone”: “string” }
città1	Città pulita	Testo	stringa
stato1	Stato chiaro	Stato	stringa
zip1	Zip trasparente	Testo	stringa
paese1	Paese chiaro	Paese	stringa
allegato1	Allegato	Selezione file	[ { “name”: “string”, “mimeType”: “string”, “fileId”: “string” } ]
drive_picker1	Selezionatore di unità	Selezionatore di unità	[ { “id”: “string”, “mimeType”: “string”, “name”: “string”, “url”: “string” } ]
firma1	Firma	Firma	{ “data”: “string”, “date”: “ISODate” }
tabella1	Tabella	Tabella dinamica	Matrice
tabella1.nuova_colonna-ta1	Nuova colonna-[tabella]	Testo	stringa
tabella1.nuova_colonna_tab1	Nuova colonna[tabella]	Valuta	{ “code”: “string”, “value”: “number” }
tabella1.nuova_colonna tab2	Nuova colonna[tabella]	Valuta	{ “code”: “string”, “value”: “number” }
palcoscenico	Stato	Palcoscenico	{ “id”: “string”, “status”: “string” }
Campi di sola lettura
creato da	Creato da	Creato da	{ “name”: “string”, “email”: “string”, “_id”: “string” }
creato il	Creato il	Creato il	ISODate
aggiornato da	Aggiornato da	Aggiornato da	{ “name”: “string”, “email”: “string”, “_id”: “string” }
aggiornato il	Aggiornato il	Aggiornato il	ISODate
recordId	ID record	ID record	{ “inc”: “number”, “value”: “string” }
approvatori	Approvatori	Approvatori

Articoli correlati sull'API

Questo articolo illustra la struttura generale dell'API Records e le chiamate/gli endpoint. I dettagli relativi alle chiamate/agli endpoint specifici sono trattati in articoli separati. Ulteriori opzioni per le chiavi API sono disponibili nella sezione API delle impostazioni della piattaforma e nella sezione Sicurezza > Chiavi API di Modifica app all'interno di ciascuna applicazione.