Présentation des API
Ne supprimez pas cet élément, car il contient des styles qui sont appliqués à l'article.
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.](../../image/uuid-7527f732-843a-d8c3-af8d-8033ad5cdccd.png)
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 .
![API keys are located under My Profile Keys.](../../image/uuid-2576fb85-3958-8e4c-e597-27e5074cb5d6.png)
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 :
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.
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.
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 estinputFile
.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" }'
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 |
| Nom de fichier du nouveau workflow. | Chaîne | Vrai |
| Nom du nouveau workflow. | Chaîne | Vrai |
| Propriétaire du workflow migré. L'adresse e-mail doit exister dans l'environnement cible. | Chaîne | Vrai |
| Indicateur pour valider le workflow lors de la migration vers l'environnement cible. | Booléen | Vrai |
| 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 |
| 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 |
| 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 |
| 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 .