Manuel du développeur d’applications

Authentification API

Lorsque vous écrivez une application qui effectue des appels d’API à Learning Manager, vous devez enregistrer votre application à l’aide de l’application d’administration d’intégration.

Les API Learning Manager utilisent l’infrastructure OAuth 2.0 pour authentifier et autoriser vos applications client.

Procédure

1. Configurer votre application

Vous pouvez configurer votre application avec l’ID client et le secret client pour utiliser les points de terminaison appropriés. Une fois l’application enregistrée, vous pouvez obtenir les paramètres clientId et clientSecret. Get URL doit être utilisé dans le navigateur, car il authentifie les utilisateurs de Learning Manager à l’aide de leurs comptes préconfigurés tels que SSO, Adobe ID, etc.

Une fois l’authentification réussie, votre navigateur se redirige vers l’URI de redirection de l’URL ci-dessus. Un code de paramètre est ajouté avec l’URI de redirection.

2. Obtenir le jeton d’actualisation à partir du code

POST https://learningmanager.adobe.com/oauth/token Content-Type: application/x-www-form-urlencoded

Corps de la demande de publication :

3. Obtenir un jeton d'accès à partir du jeton d'actualisation

URL d’obtention du jeton d’accès :

POST https://learningmanager.adobe.com/oauth/token/refresh Content-Type: application/x-www-form-urlencoded

Corps de la demande de publication :

URL de vérification des détails du jeton d’accès

GET https://learningmanager.adobe.com/oauth/token/check?access_token=<access_token>

Limitation d’utilisation

Un jeton d’accès est valide pendant sept jours. Après une journée, vous devez générer un nouveau jeton d’accès à l’aide du jeton d’actualisation. Si vous générez un nouveau jeton d’accès à partir du jeton d’actualisation alors qu’un jeton d’accès existant est toujours valide, le jeton existant est renvoyé.

Certains termes fréquemment utilisés dans l’API Learning Manager sont expliqués ci-dessous pour référence.

Inclut

Les développeurs peuvent accéder à un seul modèle d’objet API et à plusieurs modèles associés à ce modèle. Pour accéder aux modèles connexes suivants, vous devez comprendre la relation de chaque modèle avec d’autres modèles. Le paramètre Includes permet aux développeurs d'accéder aux modèles dépendants. Vous pouvez utiliser le séparateur de virgule pour accéder à plusieurs modèles. Pour obtenir un exemple d'utilisation et plus de détails sur l'inclusion, consultez la section Exemple de modèle d'API dans cette page.

Demande d’API

Les demandes d’API peuvent être faites à l’aide d’une requête HTTP. Selon le point de terminaison et le développeur de méthodes, vous avez le choix entre divers verbes HTTP, tels que GET, PUT, POST, DELETE, PATCH, etc. Pour certaines requêtes, les paramètres de requête peuvent être transmis. Lors de la création d’une requête pour un modèle de données spécifique, l’utilisateur peut également demander des modèles associés, comme décrit dans les spécifications de l’API JSON. La structure d’une demande d’API typique est décrite dans l’exemple d’utilisation du modèle.

Réponse de l’API

Lorsqu’une demande d’API est faite par un client, un document SON est obtenu conformément à la spécification de l’API JSON. La réponse contient également le code d’état HTTP, que le développeur peut vérifier pour effectuer les étapes suivantes appropriées dans sa logique d’application. La structure d'une réponse API typique est décrite dans exemple d'utilisation de modèle.

Erreurs

Lorsqu’une demande d’API échoue, une réponse Erreur est obtenue. Le code d’état HTTP renvoyé dans la réponse indique la nature de l’erreur. Les codes d’erreur sont représentés avec des numéros pour chaque modèle dans la référence API. 200, 204, 400 et 404 sont quelques-unes des erreurs courantes représentées dans les API indiquant des problèmes d’accès HTTP.

Champs

Les attributs de l’objet API et ses relations sont appelés collectivement Champs. Reportez-vous à l’API JSON pour plus d’informations. Vous pouvez utiliser Fields comme paramètre lors d'appels API pour récupérer un ou plusieurs attributs spécifiques à partir du modèle. En l’absence du paramètre Champs, l’appel API extrait tous les attributs disponibles du modèle. Par exemple, dans l'appel d'API suivant, fields[skill]=name vous récupère l'attribut name du modèle de compétence seul.

https://learningmanager.adobe.com/primeapi/v2/users/{userId}/userSkills/{id}?include=skillLevel.skill&fields[skill]=name

Pagination

Parfois, une requête API entraîne une longue liste d’objets à retourner dans la réponse. Dans de tels cas, l’attribut de pagination permet au développeur d’extraire les résultats séquentiellement en termes de pages multiples, chaque page contenant une série d’enregistrements. Par exemple, l’attribut de pagination dans Learning Manager vous permet de définir le nombre maximal d’enregistrements à afficher dans une page. En outre, vous pouvez définir la valeur de plage des enregistrements à afficher sur la page.

Tri

Le tri est autorisé dans les modèles d’API. En fonction du modèle, choisissez le type de tri à appliquer pour les résultats. Le tri peut être appliqué par ordre croissant ou décroissant. Par exemple, si vous spécifiez code sort=name, il s'agit d'un tri croissant par nom. Si vous spécifiez code sort=-name, il s'agit d'un tri décroissant par nom. Reportez-vous à la spécification technique de l'API JSON pour plus d'informations.

Illustration d’utilisation de l’API

Imaginons un scénario dans lequel un développeur souhaite obtenir le nom de la compétence, le nombre maximal de points attribués pour le niveau de compétence et les points obtenus par l’élève pour cette compétence.

Un modèle userSkill dans les API Learning Manager est constitué des attributs par défaut suivants : id, type, dateAchieved, dateCreated, pointsEarned. Ainsi, lorsqu’un développeur utilise la méthode GET pour acquérir des détails du modèle userSkill, les données actuelles relatives aux attributs par défaut sont affichées dans la sortie de réponse.

Mais, dans ce scénario, le développeur veut obtenir le nom de la compétence et les points de niveau de compétence pour l’utilisateur. L’API Learning Manager vous permet d’accéder à ces informations associées à l’aide de champs de relation et d’inclure des paramètres. Les modèles associés à userSkill sont obtenus dans la balise de relations. Vous pouvez obtenir les détails de chaque modèle associé en appelant ces modèles avec userSkill. Pour obtenir ces informations, utilisez le paramètre code include avec des valeurs séparées par des points (point) pour chacun des modèles associés. Vous pouvez utiliser une virgule comme séparateur pour demander un autre modèle comme l’utilisateur include=skillLevel.skill, course

Appel API

https://learningmanagerqe1.adobe.com/primeapi/v1/users/%7buserId%7d/userSkills/%7bid%7d?include=skillLevel.skill&fields%5bskill%5d=name&fields%5bskillLevel%5d=maxCredits&fields%5buserSkill%5d=pointsEarned

Par exemple userId peut être 746783 et userSkills id 746783_4426_1.

Réponse de l’appel API