Panoramica sulle API

Importante

Se non hai esperienza con le API, consulta la pagina di assistenza Guida introduttiva alle API .

Importante

A partire dalla versione 22.1, abbiamo rimosso gli endpoint pubblici API OAuth1 legacy perché richiedono l'hash SHA1 non conforme a FIPS. La rimozione include gli endpoint WCF (Windows Communication Framework) legacy, lo Swagger per tali endpoint e il middleware OAuth1. Per sostituire gli endpoint OAuth1, è possibile utilizzare le versioni OAuth2 delle API legacy rilasciate nella versione 21.4 e conformi a FIPS. Le API OAuth2 offrono le stesse funzionalità delle API OAuth1.

Gli endpoint Subscription, V1 e V2 continueranno a essere supportati in OAuth2.

Per ulteriori informazioni sulla conversione e sul suo impatto, visita la pagina della guida Istruzioni da OAuth1 a OAuth2 o Istruzioni per la conversione .

L'API Server è composta da 5 API:

API di iscrizione : endpoint che consentono agli utenti di interagire con iscrizioni, flussi di lavoro e pianificazioni (processi).
API V2 utente : endpoint che consentono agli utenti di interagire con credenziali, file di input e programmazioni (processi).
API V1 di amministrazione : endpoint che consentono agli amministratori di recuperare le risorse dall'interfaccia di amministrazione.
API V2 di amministrazione : versione 2 degli endpoint che consente agli amministratori di recuperare le risorse dall'interfaccia di amministrazione.
API V3 di amministrazione : versione 3 degli endpoint. Questa versione utilizza Oauth 2.

Nota

Oltre ad aggiungere nuove funzionalità con gli endpoint dell'API V3 , abbiamo reso disponibili anche gli endpoint V1, di iscrizione e V2 per l'utilizzo con Oauth 2. Gli stessi endpoint che hai utilizzato in passato sono ora disponibili per Oauth 2 a un nuovo indirizzo base.

L'indirizzo API Web può essere impostato solo per V1, V2 e V3 con Oauth 2. Per la documentazione relativa all'API V1 e V2 con Oauth 1, l'indirizzo è http://{ServerHostname}/gallery/api-docs/ .

The Web API address can be set up in System Settings.

Accesso ai documenti di riferimento dell'API Server

La documentazione di riferimento completa per tutti gli endpoint dell'API Server è disponibile in Swagger.

La documentazione di riferimento dell'API Server è accessibile in due posizioni nell'interfaccia utente di Server.

Seleziona l'icona con il punto interrogativo nella barra degli strumenti superiore e scegli Documentazione API .
Seleziona il tuo nome utente e scegli Profilo personale > Chiavi . Accanto alle chiavi API sono disponibili i collegamenti alla documentazione API.

Puoi anche accedere alla documentazione di riferimento per l'API Server tramite il seguente URL: http(s)://serverhostname.domain/webapi/swagger

Autenticazione per i documenti di riferimento dell'API Server

I documenti relativi all'API Server sono interattivi e consentono di compilare i parametri e visualizzare le risposte. Per sfruttare questa interattività, è necessario eseguire l'autenticazione attenendoti alla seguente procedura:

Nell'interfaccia utente di Server, seleziona il tuo nome utente e scegli Profilo personale > Chiavi . Copia le chiavi per l'API a cui desideri autenticarti e incollale nei campi Chiave API e Chiave segreta condivisa . Le chiavi vengono visualizzate come Salvate .
Seleziona la chiamata che desideri eseguire, compila i parametri e scegli Prova .

Chiavi API e accesso all'API

Gli amministratori (di Server) devono autorizzare gli utenti ad accedere all'API. Per ulteriori informazioni, consulta Accesso degli utenti all'API Server . Una volta ottenuto l'accesso all'API, gli utenti possono trovare le chiavi API nella scheda Chiavi della pagina Profilo personale . Per accedere alle chiavi API, seleziona il tuo nome utente e scegli Profilo personale > Chiavi .

Gli utenti con ruolo di amministratore possono utilizzare le chiavi di accesso all'API per accedere a tutte le API, inclusa l'API di iscrizione, l'API V2 utente, l'API V1 di amministrazione, l'API V2 di amministrazione e l'API V3.

Tutti gli utenti che non hanno il ruolo di amministratore possono utilizzare le chiavi di accesso all'API per accedere all'API di iscrizione e all'API V2 utente.

Tutti gli utenti possono utilizzare le chiavi API di Private Studio per accedere all'API di sottoscrizione.

Costruzione degli endpoint API

Per costruire un endpoint API, utilizza questo schema: <hostname>/webapi/

Autenticazione

Consulta l'articolo Configurazione e autorizzazione dell'API Server .

Endpoint e parametri API

In questa sezione troverai ulteriori informazioni sui seguenti endpoint:

Endpoint del registro di controllo

Server tiene traccia delle modifiche apportate alle seguenti entità di sistema:

AppInfo (flusso di lavoro)
Raccolta
Credenziale
Iscrizione
Utente
UserGroup

Recupero degli eventi registrati tramite l'API Server

Eventuali aggiornamenti a queste entità attivano la creazione di un record AuditEvent. È possibile restituire questi record tramite un endpoint API di un amministratore pubblico.

Endpoint

L'endpoint per AuditEvents è GET /admin/v1/auditlog/

Parametri di query richiesti

entity: (string) l'entità del log di controllo per la quale si desidera eseguire una query.
page: (int) la pagina che si desidera restituire.
pageSize: (int) il numero di record da restituire in ogni pagina.

La risposta sarà una serie di record Evento di controllo:

[
  {
    "id": "",
    "entity": "",
    "entityId": "",
    "userId": "",
    "timestamp": "Date",
    "event": "",
    "oldValues": "",
    "newValues": ""
  }
]

Le proprietà restituite sono definite di seguito:

id: l'ID dell'evento di controllo.
entity: il nome dell'entità.
entityId: l'ID dell'entità.
userId: l'ID dell'utente che ha modificato l'entità.
timestamp: la data e l'ora di creazione del record Evento di controllo.
event: l'evento che si è verificato (inserimento, aggiornamento, eliminazione).
oldValues: i valori delle proprietà aggiornate prima dell'aggiornamento.
newValues: i valori delle proprietà aggiornate dopo l'aggiornamento.

Endpoint Inputfiles

Per eseguire i flussi di lavoro che utilizzano lo strumento Sfoglia file tramite l'API, utilizza l'endpoint /user/v2/inputfiles per caricare il file. Strumento Sfoglia file

Inizia inoltrando una richiesta POST multipart/form-data all'endpoint /user/v2/inputfiles per pubblicare un file temporaneo. Il nome della sezione form-data richiesta è inputFile.
```
curl --location --request POST 'http:{yourhostname}/api/user/v2/inputfiles/' \
--form 'inputFile=@/file/path/filename.csv' 
```

Quindi, invia una richiesta POST all'endpoint /user/v2/workflows/{appId}/jobs/.

Successivamente, includi il nome dello strumento Sfoglia file nell'oggetto della domanda. In caso di dubbi sul nome dello strumento Sfoglia file, utilizza l'endpoint /v1/workflows/{appId}/questions per scoprirlo.
Il valore è l'ID di riferimento restituito nella risposta dalla chiamata al file di input.

curl --location --request POST 'http:{yourhostname}/api/user/v2/workflows/{appId}/jobs' \
--header 'Content-Type: text/plain' \
--header 'Authorization: OAuth oauth_consumer_key="{consumer key}",
                         oauth_signature_method="HMAC-SHA1",
                         oauth_timestamp="{timestamp}",
                         oauth_nonce="{nonce}",
                         oauth_signature="{signature}"' \
--data-raw '{
    "questions": [
        {
            "name": "File Browse",
            "value": "{reference ID}"
        }
    ]
    "priority": "Low"
}'

Endpoint migratable

Utilizza l'endpoint migratable per migrare i flussi di lavoro tra gli ambienti di Server. Puoi utilizzare questo endpoint per gestire le distribuzioni dei flusso di lavoro durante le fasi di sviluppo e test.

Per iniziare, è necessario abilitare i flussi di lavoro per la migrazione . Dopo aver contrassegnato i flussi di lavoro per la migrazione, attieniti alla procedura di seguito per pubblicarli dall'ambiente di origine nell'iscrizione appropriata (studio) dell'ambiente di destinazione.

Passaggio 1. Ottieni un elenco dei flussi di lavoro pronti per la migrazione

Successivamente, ottieni un elenco di flussi di lavoro pronti per la migrazione utilizzando il seguente endpoint:

Ambiente: origine
Metodo: GET
Endpoint: api/admin/v1/workflows/migratable/?subscriptionIds={subscriptionIds}/

Includi un elenco separato da virgole di subscriptionIds come parametro di query. Gli ID iscrizione identificano uno studio specifico.

Il risultato è una serie di flussi di lavoro contrassegnati come pronti per la migrazione nell'iscrizione specificata (studio). Se non fornisci subscriptionIds, vengono forniti tutti i flussi di lavoro contrassegnati come pronti per la migrazione. Il risultato include 3 proprietà: appId, revisionid attualmente pubblicato e subscriptionID di appartenenza del flusso di lavoro.

Passaggio 2. Scarica i flussi di lavoro dall'ambiente di origine

Il seguente endpoint scarica il flusso di lavoro come file YXZP.

Ambiente: origine
Metodo: GET
Endpoint: api/admin/v1/{appID}/package/

Includi un appID come parametro di percorso. Il risultato sarà un download dell'intero flusso di lavoro come pacchetto.

Passaggio 3. Pubblica i flussi di lavoro nell'ambiente di destinazione

Il seguente endpoint pubblica il flusso di lavoro scaricato nell'ambiente di destinazione.

Ambiente: destinazione
Metodo: POST
Endpoint: api/admin/v1/workflows/

Parametri
Parametro	Descrizione	Tipo	Obbligatorio
`file`	Il nome file del nuovo flusso di lavoro.	Stringa	True
`name`	Il nome del nuovo flusso di lavoro.	Stringa	True
`owner`	Il proprietario del flusso di lavoro migrato. L'indirizzo e-mail deve esistere nell'ambiente di destinazione.	Stringa	True
`validate`	Contrassegno per convalidare il flusso di lavoro durante la migrazione all'ambiente di destinazione.	Booleano	True
`isPublic`	Contrassegno per impostare il flusso di lavoro come pubblico e visualizzarlo in "Gallery della mia azienda" nell'ambiente di destinazione.	Booleano	True
`sourceId`	L'appId dell'ambiente di origine del flusso di lavoro da migrare. Se è presente un flusso di lavoro con lo stesso sourceId, questo sostituisce il flusso di lavoro nell'ambiente di destinazione. In caso contrario, viene generato un nuovo flusso di lavoro. (Invia una stringa vuota se non desideri specificare un appID.)	Stringa	True
`workerTag`	Aggiungi un tag worker al flusso di lavoro se desideri che questo sia eseguito da un worker specifico. (Invia una stringa vuota se non desideri specificare un worker.)	Stringa	True
`canDownload`	Contrassegno per impostare il flusso di lavoro come disponibile per il download da parte di altri utenti nell'ambiente di destinazione.	Booleano	True

Passaggio 4 (facoltativo). Ripristina i flussi di lavoro delle impostazioni di migrazione nell'ambiente di origine

Puoi utilizzare l'endpoint migratable per ripristinare l'impostazione Questo flusso di lavoro è pronto per la migrazione di un flusso di lavoro su No nell'ambiente di origine dopo la migrazione del flusso di lavoro nell'ambiente di destinazione.

Ambiente: origine
Metodo: PUT
Endpoint: api/admin/v1/workflows/migratable/{appID}/

Per ulteriori informazioni sugli endpoint e i parametri dell'API Server V3, consulta la pagina di assistenza API Alteryx Server V3 .

In questa sezione: