Présentation des API

Important

Si vous débutez avec les API, consultez la page d'aide Pour commencer avec les API .

Important

À partir de la version 22.1, nous avons supprimé nos points de terminaison d'API OAuth1 publics hérités car ils nécessitent un hachage SHA1 non conforme à la norme FIPS. Cette suppression inclut les points de terminaison WCF (Windows communication Framework) hérités, Swagger pour ces points de terminaison hérités et le middleware OAuth1. Pour remplacer les points de terminaison OAuth1, vous pouvez utiliser les versions OAuth2 des API héritées publiées dans la version 21.4, qui sont conformes à la norme FIPS. Vous obtiendrez la même fonctionnalité avec les API OAuth2 que celle disponible avec les API OAuth1.

La souscription et les points de terminaison V1 et V2 continueront d'être pris en charge sous OAuth2.

Pour en savoir plus sur la conversion et son impact, consultez la page d'aide Instructions de migration d'OAuth1 vers OAuth2 ou les instructions de conversion .

L'API Server est composée de 5 API :

API de souscription : points de terminaison permettant aux utilisateurs d'interagir avec les souscriptions, les workflows et les planifications (tâches).
API User V2 : points de terminaison permettant aux utilisateurs d'interagir avec les identifiants, les fichiers d'entrée et les planifications (tâches).
API Admin V1 : points de terminaison permettant aux administrateurs d'extraire des ressources de l'interface administrateur.
API Admin V2 : version 2 des points de terminaison permettant aux administrateurs d'extraire des ressources de l'interface administrateur.
API Admin V3 : version 3 des points de terminaison. Cette version utilise OAuth 2.

Note

En plus d'ajouter de nouvelles fonctionnalités avec les points de terminaison de l'API V3 , nous rendons nos points de terminaison V1, de souscription et V2 compatibles pour l'utilisation avec OAuth 2. Les points de terminaison que vous utilisiez au préalable sont désormais disponibles pour OAuth 2 à une nouvelle adresse de base.

L'adresse de l'API Web ne peut être configurée que pour V1, V2 et V3 utilisant OAuth2. Pour la documentation de l'API V1 et V2 utilisant OAuth 1, l'adresse est http://{ServerHostname}/gallery/api-docs/ .

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

Accéder aux documents de référence de l'API Server

La documentation de référence complète relative à tous les points de terminaison de l'API Server est disponible dans Swagger.

L'interface utilisateur Server présente deux emplacements où vous pouvez accéder à la documentation de référence de l'API Server.

Sélectionnez l'icône en forme de point d'interrogation dans la barre d'outils supérieure et sélectionnez Documentation API .
Sélectionnez votre nom d'utilisateur, puis Mon Profil > Clés . Des liens vers la documentation API sont disponibles en regard des clés API.

Vous pouvez également accéder à la documentation de référence de l'API Server à l'aide de l'URL suivante : http(s)://serverhostname.domain/webapi/swagger

Authentification sur l'espace de la documentation de référence de l'API Server

Les documents de l'API Server sont interactifs, ce qui vous permet de renseigner les paramètres et de voir les réponses. Pour utiliser l'interactivité, vous devez vous authentifier. Pour ce faire, procédez comme suit :

Dans l'interface utilisateur Server, sélectionnez votre nom d'utilisateur, puis Mon Profil > Clés . Copiez les clés API de l'API à laquelle vous souhaitez vous authentifier et collez-les dans les champs Clé API et Secret partagé . Les clés s'afficheront avec le statut Enregistré .
Sélectionnez l'appel que vous souhaitez exécuter, renseignez les paramètres et sélectionnez Essayer .

Clés et accès API

Les administrateurs de Server doivent autoriser les utilisateurs à accéder à l'API. Pour plus d'informations, consultez Autoriser l'utilisateur à accéder à l'API Server . Une fois que vous avez accordé aux utilisateurs l'accès à l'API, ils peuvent trouver leurs clés API dans l'onglet Clés de la page Mon Profil . Pour accéder à vos clés API, sélectionnez votre nom d'utilisateur, puis Mon Profil > Clés .

Les utilisateurs ayant le rôle d'administrateur peuvent utiliser les clés d' accès à l'API pour accéder à toutes les API, y compris l'API de souscription, l'API User V2, l'API Admin V1, l'API Admin V2 et l'API V3.

Tous les utilisateurs non-administrateurs peuvent utiliser les clés d' accès à l'API pour accéder à l'API de souscription et à l'API User V2.

Tous les utilisateurs peuvent utiliser les clés de l'API Private Studio pour accéder à l'API Subscription.

Construction de points de terminaison d'API

Pour construire un point de terminaison d'API, utilisez ce schéma : <hostname>/webapi/

Authentification

Reportez-vous à l'article Configuration et autorisation de l'API Server .

Points de terminaison et paramètres API

Dans cette section, vous trouverez plus d'informations sur les points de terminaison suivants :

Point de terminaison du journal d'audit

Server suit les modifications apportées aux entités système suivantes :

AppInfo (workflow)
Collection
Informations d'identification
Souscription
Utilisateur
UserGroup

Obtenir les événements consignés via l'API Server

Toute mise à jour de ces entités déclenche la création d'un enregistrement d'événement d'audit. Vous pouvez renvoyer ces enregistrements via un point de terminaison d'API administrateur public.

Point de terminaison

Le point de terminaison pour AuditEvents est GET /admin/v1/auditlog/

Paramètres de requête requis

entity : (chaîne) entité du journal d'audit à interroger.
page : (int) page que vous voulez renvoyer.
pageSize : (int) nombre d'enregistrements que vous voulez renvoyer sur chaque page.

La réponse sera renvoyée sous la forme d'un tableau d'enregistrements d'événements d'audit :

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

Les propriétés renvoyées sont définies ci-dessous :

id : ID de l'événement d'audit.
entity : nom de l'entité.
entityId : ID d'entité de l'entité.
userId : ID de l'utilisateur qui a modifié l'entité.
timestamp : date et heure de création de l'enregistrement de l'événement d'audit.
event : événement qui s'est produit (insertion, mise à jour, suppression).
oldValues : valeurs des propriétés modifiées avant la mise à jour.
newValues : valeurs des propriétés modifiées après la mise à jour.

Point de terminaison Inputfiles

Pour exécuter des workflows qui utilisent l' outil Explorateur de fichiers via l'API, utilisez le point de terminaison /user/v2/inputfiles pour charger le fichier. Outil Explorateur de fichiers

Commencez par formuler une requête POST multipart/form-data au point de terminaison /user/v2/inputfiles pour publier un fichier temporaire. Le nom de la section de données de formulaire requise est inputFile.
```
curl --location --request POST 'http:{yourhostname}/api/user/v2/inputfiles/' \
--form 'inputFile=@/file/path/filename.csv' 
```

Ensuite, effectuez un POST sur le point de terminaison /user/v2/workflows/{appId}/jobs/.

Ajoutez ensuite le nom de l'outil Explorateur de fichiers dans l'objet de la question. Si vous n'êtes pas sûr du nom de l'outil Explorateur de fichiers, utilisez le point de terminaison /v1/workflows/{appId}/questions pour l'obtenir.
La valeur est l'ID de référence renvoyé par l'appel de votre fichier d'entrée dans la réponse.

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"
}'

Point de terminaison migratable

Utilisez le point de terminaison migratable pour migrer les workflows dans les environnements de Server. Vous pouvez l'utiliser pour gérer les déploiements de workflows pendant les phases de développement et de test.

Pour commencer, vous devez activer les workflows pour la migration . Une fois que vous avez marqué des workflows pour la migration, suivez ces étapes pour les publier à partir de l'environnement source dans la souscription appropriée (studio) d'un environnement cible.

Étape 1. Obtenez une liste des workflows prêts pour la migration

Ensuite, obtenez une liste des workflows prêts pour la migration à l'aide du point de terminaison suivant :

Environnement : source
Méthode : GET
Point de terminaison : api/admin/v1/workflows/migratable/?subscriptionIds={subscriptionIds}/

Incluez une liste de subscriptionIds séparés par des virgules comme paramètre de requête. Les ID de souscription identifient un studio spécifique.

Vous obtenez un tableau des workflows marqués comme prêts pour la migration sous la souscription spécifiée (studio). Si vous ne fournissez pas de subscriptionsIds, le résultat inclut tous les workflows marqués comme prêts pour la migration. Le résultat inclut 3 propriétés : l' appId, le revisionId actuellement publié et le subscriptionID auquel appartient le workflow.

Étape 2. Téléchargez des workflows à partir de l'environnement source

Le point de terminaison suivant télécharge le workflow sous forme de fichier YXZP.

Environnement : source
Méthode : GET
Point de terminaison : api/admin/v1/{appID}/package/

Incluez un appID comme paramètre de chemin. Vous obtiendrez un téléchargement de l'ensemble du workflow sous forme de package.

Étape 3. Publiez des workflows dans l'environnement cible

Le point de terminaison suivant publie le workflow téléchargé dans l'environnement cible.

Environnement : cible
Méthode : POST
Point de terminaison : api/admin/v1/workflows/

Paramètres
Paramètre	Description	Type	Obligatoire
`file`	Nom de fichier du nouveau workflow.	Chaîne	Vrai
`name`	Nom du nouveau workflow.	Chaîne	Vrai
`owner`	Propriétaire du workflow migré. L'adresse e-mail doit exister dans l'environnement cible.	Chaîne	Vrai
`validate`	Indicateur pour valider le workflow lors de la migration vers l'environnement cible.	Booléen	Vrai
`isPublic`	Indicateur pour définir le workflow sur public afin de l'afficher dans « Galerie de ma société » dans l'environnement cible.	Booléen	Vrai
`sourceId`	Il s'agit de l'appId de l'environnement source du workflow à migrer. Si un workflow avec le même sourceId existe, il remplace ce workflow dans l'environnement cible. Dans le cas contraire, un nouveau workflow sera généré. (Envoyez une chaîne vide si vous ne souhaitez pas spécifier d'appID.)	Chaîne	Vrai
`workerTag`	Ajoutez une balise worker au workflow pour qu'un worker spécifique exécute le workflow. (Envoyez une chaîne vide si vous ne souhaitez pas spécifier de worker.)	Chaîne	Vrai
`canDownload`	Indicateur pour définir le workflow comme disponible au téléchargement par d'autres utilisateurs dans l'environnement cible.	Booléen	Vrai

(Facultatif) Étape 4. Réinitialisez les workflows de paramétrage de migration dans l'environnement source

Si vous le souhaitez, vous pouvez utiliser le point de terminaison migratable pour définir le paramètre Ce workflow est prêt à être migré sur Non dans l'environnement source après la migration du workflow dans l'environnement cible.

Environnement : source
Méthode : PUT
Point de terminaison : api/admin/v1/workflows/migratable/{appID}/

Pour plus d'informations sur les points de terminaison et les paramètres V3 de l'API, consultez la page d'aide API Alteryx Server V3 .

Dans cette section: