Choses à faire avant de commencer
Avant de pouvoir commencer avec ce tutoriel, vous devez avoir suivi les 3 étapes ci-dessous :
- Demander les informations d'identification de l'API du membre Sandbox
- Créer un bac à sable ORCID Compte
- Configurez votre terrain de jeu google oauth
Pour ce tutoriel, nous utiliserons ORCIDde l'environnement de test, le ORCID Sandbox. Le Sandbox fonctionne exactement comme la production ORCID Registre, à quelques exceptions près :
- Sandbox envoie uniquement des e-mails à mailinator.com adresses
- La majorité des outils de l'assistant d'importation ne fonctionnent pas dans la Sandbox
- Les liens de menu vers le contenu informatif (À propos, Pour les chercheurs, Adhésion, etc.) ne fonctionnent pas dans la Sandbox
- Sandbox ne contient aucune donnée de production
Demander les informations d'identification de l'API du membre Sandbox
Les informations d'identification de l'API consistent en un identité du client et un secret client qui sont nécessaires pour collecter des identifiants authentifiés et/ou des autorisations d'utilisateurs pour interagir avec leurs ORCID enregistrement. Veuillez demander vos identifiants Sandbox ici. Ajoutez une note pour indiquer que vous testez avec Google OAuth Playground. Veuillez noter qu'il s'agit d'un processus manuel et que la création des informations d'identification peut prendre jusqu'à 24 heures.
Créer un bac à sable ORCID Compte
Dans une nouvelle fenêtre ou un nouvel onglet, visitez https://sandbox.orcid.org/register
- Entrez votre nom et votre adresse e-mail, puis cliquez sur le bouton "Suivant". IMPORTANT! N'utilisez pas une vraie adresse e-mail ! Au lieu de cela, composez une adresse se terminant par @mailinator.com
- Complétez l'étape 2 du formulaire d'inscription avec un mot de passe, et passez à l'étape 3.
- Sélectionnez votre paramètre de visibilité préféré, acceptez les conditions d'utilisation, cliquez sur la case à côté du texte "Je ne suis pas un robot", et enfin cliquez sur le bouton "s'inscrire".
N'oubliez pas l'e-mail et le mot de passe - vous en aurez besoin tout au long du didacticiel !
Configurez votre Terrain de jeu Google OAuth
- Cliquez sur Terrain de jeu Google OAuth
- Cliquez sur l'icône d'engrenage dans le coin supérieur droit pour ouvrir le Configuration OAuth 2.0
- Modifiez la liste déroulante des points de terminaison Oauth sur Personnalisé et entrez les paramètres suivants et cliquez sur Fermer
Important! Gardez le terrain de jeu Google OAuth ouvert afin de ne pas perdre les configurations que vous avez effectuées dans les étapes ci-dessus. Vous pouvez également enregistrer l'URL qui vous permet d'initialiser le Playground avec ces configurations (pour obtenir l'URL, cliquez sur l'icône de lien à côté de l'icône d'engrenage dans le coin supérieur droit).
Collecte authentifiée ORCID identifiants et autorisations
ORCID les intégrations utilisent «OAuth en 3 étapes» pour authentifier les utilisateurs et demander l'autorisation d'interagir avec leurs enregistrements. Toute intégration peut demander des autorisations de lecture à l'aide de l'API publique. ORCID les membres peuvent utiliser l'API des membres pour demander des autorisations de lecture et d'écriture.
Dans cette section, nous allons parcourir les étapes que votre propre intégration personnalisée devrait suivre pour obtenir un compte authentifié iD et l'autorisation de lire et d'écrire à un ORCID record
Obtenir un authentifié iD et l'autorisation d'accès à l'enregistrement d'un utilisateur implique de suivre OAuth 2.0, un protocole d'autorisation standard de l'industrie. OAuth permet à un utilisateur de donner à un site Web ou à une application l'accès aux informations de compte stockées sur un autre site, sans donner à ce site son mot de passe.
Si vous vous êtes déjà connecté à un site en utilisant Google ou Facebook au lieu de vos informations d'identification pour ce site particulier, vous avez déjà utilisé OAuth !
Le processus OAuth comprend 3 étapes :
- Créer une URL d'autorisation
- Obtenir un code d'autorisation
- Échangez le code d'autorisation contre un jeton d'accès
Pour lancer le processus OAuth, nous devrons créer une URL d'autorisation spéciale qui envoie les utilisateurs vers un ORCID écran de connexion. Cette URL se compose de Point de terminaison d'autorisation, ainsi que Paramètres qui identifient votre organisation et les autorisations que vous souhaitez demander.
Pour demander l'autorisation d'ajouter/de mettre à jour des activités (affiliations, financement, travaux, évaluation par les pairs, ressources de recherche) et d'ajouter/de mettre à jour des éléments personnels (autres noms, mots clés, pays, URL de chercheur, sites Web et identifiants externes personnels), le l'URL d'autorisation sera :
https://sandbox.orcid.org/oauth/authorize?client_id=[APP-****************]&response_type=code&scope=/read-limited%20/activities/update%20/person/update&redirect_uri=https://developers.google.com/oauthplaygroundMais nous pouvons utiliser Google OAuth playground pour nous aider à créer l'URL d'autorisation
Ajoutez /activities/update, /person/update, /read-limited dans le champ scopes et cliquez sur allow API's.
L'URL d'autorisation aurait été créée à l'aide des informations que vous avez saisies dans les champs de configuration et de portée.
An ORCID l'écran de connexion apparaîtra ; connectez-vous à votre compte Sandbox avec l'adresse e-mail et le mot de passe que vous avez utilisés pour créer votre ORCID compte au début de ce didacticiel. Une fois connecté, l'écran OAuth apparaîtra. Le nom du client et les étendues pertinentes incluses dans l'URL d'autorisation s'afficheront sur cet écran. Pour accorder l'accès, vous devez cliquer sur 'Autoriser l'accès'
Après avoir accordé l'autorisation, vous serez redirigé vers Google OAuth Playground car il s'agissait de l'URI de redirection associée à vos informations d'identification Sandbox. Un code d'autorisation à 6 caractères apparaîtra à la fin de l'URI de redirection dans la barre d'adresse du navigateur (et sous le Étape 2 section à gauche de la page dans google oauth playground)
Une fois que vous avez un code d'autorisation, vous pouvez l'échanger contre un jeton d'accès et le code d'authentification authentifié. iD de l'utilisateur qui s'est connecté, dont vous aurez besoin pour effectuer la ou les actions d'API pour lesquelles vous avez demandé l'autorisation.
Si vous perdez le jeton d'accès, vous pouvez recommencer le processus, mais vous devez d'abord révoquer l'autorisation pour l'application cliente si vous utilisez le même ORCID identifiant. L'autorisation peut être révoquée en supprimant l'application cliente de la section "Organisations de confiance" de la page "Parties de confiance"
Dans une situation réelle, cet échange serait effectué par votre système, à l'aide d'un langage de programmation tel que PHP, Java ou Ruby on Rails. Pour ce didacticiel, nous utiliserons Google OAuth Playground pour simuler une application Web.
Cliquez 'Code d'autorisation d'échange pour les jetons'
Une fois que vous cliquez sur “Code d'autorisation d'échange pour les jetons” Votre jeton d'accès et authentifié iD apparaîtra dans le Demande de réponse partie à droite. Veuillez voir l'exemple ci-dessous :
Enregistrez ce jeton !
Il est important de sauvegarder le jeton que vous avez reçu à l'étape ci-dessus car vous pouvez facilement créer tous les appels que vous devez passer avec. Nous vous recommandons de stocker la réponse d'échange de jeton complète
Vous avez maintenant collecté un authentifié ID et l'autorisation de l'utilisateur de lire son ORCID enregistrer et mettre à jour leurs ORCID record.
Écrire à un ORCID enregistrement (POST)
Dans cette section, nous ajouterons une affiliation éducative à votre enregistrement Sandbox. Dans l'exemple suivant, nous utilisons le point de terminaison /education avec le XML correct pour ajouter l'information, mais vous pouvez tout aussi bien ajouter Emploi ou Travail par exemple. Voir notre Documentation Github pour plus d'exemples de fichiers et de points de terminaison et les autorisations dont vous avez besoin pour chacun.
Voici un exemple de fichier XML pour l'éducation que vous pouvez utiliser pour cet exercice :
<?xml version="1.0" encoding="UTF-8"?>
<education:education
xmlns:common="http://www.orcid.org/ns/common" xmlns:education="http://www.orcid.org/ns/education"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.orcid.org/ns/education ../education-3.0.xsd ">
<common:department-name>department-name</common:department-name>
<common:role-title>role-title</common:role-title>
<common:start-date>
<common:year>1948</common:year>
<common:month>02</common:month>
<common:day>02</common:day>
</common:start-date>
<common:end-date>
<common:year>1948</common:year>
<common:month>02</common:month>
<common:day>02</common:day>
</common:end-date>
<common:organization>
<common:name>common:name</common:name>
<common:address>
<common:city>common:city</common:city>
<common:region>common:region</common:region>
<common:country>AF</common:country>
</common:address>
<common:disambiguated-organization>
<common:disambiguated-organization-identifier>http://dx.doi.org/10.13039/100000001</common:disambiguated-organization-identifier>
<common:disambiguation-source>FUNDREF</common:disambiguation-source>
</common:disambiguated-organization>
</common:organization>
<common:url>http://tempuri.org</common:url>
<common:external-ids>
<common:external-id>
<common:external-id-type>grant_number</common:external-id-type>
<common:external-id-value>external-identifier-value</common:external-id-value>
<common:external-id-url>http://tempuri.org</common:external-id-url>
<common:external-id-relationship>self</common:external-id-relationship>
</common:external-id>
<common:external-id>
<common:external-id-type>grant_number</common:external-id-type>
<common:external-id-value>external-identifier-value2</common:external-id-value>
<common:external-id-url>http://tempuri.org/2</common:external-id-url>
<common:external-id-relationship>self</common:external-id-relationship>
</common:external-id>
</common:external-ids>
</education:education>Revenez à l'onglet du navigateur pour Google Playground. Si vous n'avez pas laissé l'onglet ouvert, vous pouvez réinitialiser la session avec l'URL que vous avez enregistrée précédemment (en cliquant sur OK sur l'avertissement qui s'affiche). Ou vous pouvez configurer à nouveau l'appel en remplissant tous les champs pertinents, en vous assurant qu'ils ressemblent aux captures d'écran ci-dessous :
- Assurez-vous que le paramétrage a votre client ID et secret client
- ci-dessous Étape 2 dans le terrain de jeu google oauth, vous devriez avoir votre jeton d'accès rempli
Il devrait toujours avoir le jeton du précédent ou vous pouvez le remplir à partir de l'exercice précédent comme ceci : - Sous l'étape 3, cliquez sur Ajouter des en-têtes, entrez les valeurs ci-dessous, puis cliquez sur Ajouter et Fermé
- Nom de l'en-tête : Accepter
- Valeur d'en-tête : application/vnd.orcid+xml
- Sous Étape 3 : Configurer la demande à l'API, définissez la méthode HTTP sur POST.
- Dans le URI de la demande champ saisir :
https://api.sandbox.orcid.org/v3.0/[ORCID ID]/education
Remplacer [ORCID ID] avec le iD pour votre enregistrement Sandbox, formatez XXXX-XXXX-XXXX-XXXX avec lequel vous avez obtenu l'autorisation d'interagir. - Cliquez Type de contenu > Applications et entrez application/vnd.orcid+xml Clic Ajouter, puis clique Fermé.
- Cliquez Saisir le corps de la demande.
Copiez le fichier XML d'affiliation scolaire en haut de cette section et collez-le dans le Corps de la demande zone de texte
OPTION: Dans le Corps de la demande zone de texte, modifiez le XML pour refléter votre institution.
Pour , Utilisez le Registre RDR pour trouver le ROR ID pour votre institutn.
Cliquez Fermé.
- Cliquez Envoyez la demande.
Les résultats apparaîtront dans le Demande de réponse section à droite. Faites défiler vers le bas - si vous voyez HTTP/1.1 201 Créé, votre affiliation scolaire a été ajoutée avec succès !
Enregistrez également votre put code qui vous sera demandé dans la section suivante !
Visitez la vue publique de votre enregistrement Sandbox sur https://sandbox.orcid.org/[ORCID ID] pour voir votre nouvelle affiliation scolaire.
Notez que Source affiche le nom du client API qui a ajouté l'affiliation - c'est un élément clé qui aide les autres systèmes à consommer ORCID données déterminent si cette information fait autorité.
Mise à jour d'un ORCID enregistrer (PUT)
Dans une situation réelle, vous devrez peut-être mettre à jour l'affiliation d'un chercheur. Dans cette section, nous mettrons à jour notre affiliation à l'éducation pour inclure une date de fin.
Les codes Put sont des codes numériques courts qui font référence à un élément particulier sur le ORCID enregistrement. Vous utilisez le code put avec les appels d'API pour mettre à jour, supprimer ou lire un élément particulier (par opposition à un résumé des éléments.)
Chaque élément du ORCID iD se voit attribuer un code put qui l'identifie de manière unique. Lors de la lecture d'un enregistrement ou d'une section entière, le code put peut être trouvé en tant qu'attribut de l'élément. Lorsque appeler un élément spécifique d'un enregistrement, le code put est utilisé pour identifier l'article. Les codes de placement sont uniques dans le type d'élément auquel ils se réfèrent. En utilisant cet exemple, un seul travail dans le ORCID Le registre aura le code put 733535, bien que 733535 puisse également être utilisé comme code put pour un élément de financement ou un mot-clé.
Lorsque vous publiez un élément dans l'enregistrement d'un chercheur, la réponse de l'API contiendra le code put de cet élément. Vous pouvez stocker le code put pour l'utiliser plus tard si vous avez besoin de lire, mettre à jour ou supprimer cet élément.
Pour connaître le code de mise d'un article particulier que nous n'avons pas, il nous suffit de lire l'enregistrement ou un résumé de la section où se trouve cet article. Le code put de l'élément que nous voulons modifier sera renvoyé dans la réponse.
Dans l'exemple ci-dessous, nous mettons à jour un seul élément d'éducation.
Remarque : si vous avez enregistré le code put pour votre affiliation scolaire, vous pouvez passer à l'étape 4 ci-dessous. Si vous n'avez pas enregistré le code put, veuillez commencer par l'étape 1 ci-dessous.
- Nous devons d'abord obtenir un mettre le code pour l'affiliation éducative que vous venez d'ajouter, ouvrez une nouvelle fenêtre Google Playground et configurez-la en suivant les 4 premières étapes de la section de démarrage
- Cette fois, dans le champ Request URI, entrez https://api.sandbox.orcid.org/v3.0/0000-XXXX-XXXX-XXXX/educations . Notez que nous avons ajouté /educations à la fin de l'URI et qu'il est au pluriel. Cela signifie que nous récupérons un résumé de tous les éléments d'éducation de cet enregistrement, pas un seul (nous le mettrions au singulier et ajouterions le /put-code de l'élément à la fin)
- Cliquez sur "Envoyer la demande" et vous devriez voir quelque chose comme l'image ci-dessous dans le Demande de réponse section. Trouvez le put-code pour l'affiliation scolaire que vous avez ajoutée dans la section précédente (il s'agira d'un numéro différent de celui mis en évidence ici).
- Modifier Méthode HTTP à PUT
- Cliquez Ajouter des en-têtes et assurez-vous que Accept et Content-type sont tous deux définis sur application/vnd.orcid+xml
- Dans le URI de la demande champ saisir :
https://api.sandbox.orcid.org/v3.0/[ORCID ID]/education/[PUT CODE]
Remplacer [ORCID ID] avec le iD pour votre enregistrement Sandbox, formatez XXXX-XXXX-XXXX-XXXX et [PUT CODE] avec le put-code pour votre affiliation scolaire - Récupérez à nouveau le XML de la section POST et cliquez sur Saisir le corps de la demande et collez-le.
- Modifier la date de fin de votre affiliation scolaire
- Cliquez Fermé.
- Cliquez sur Envoyer la demande.
- Les résultats apparaîtront dans le Demande de réponse section à droite. Faites défiler vers le bas - si vous voyez HTTP / 1.1 200 OK, votre affiliation scolaire a été mise à jour avec succès ! Si un message d'erreur s'affiche, vérifiez que les valeurs d'en-tête dans Ajouter des en-têtes n'ont pas été modifiés en texte tronqué, par exemple : application%2Fvnd.orcid%2Bxml"
- Rendez-vous sur vue publique de votre enregistrement Sandbox à https://sandbox.orcid.org/[ORCID ID] pour voir votre affiliation scolaire mise à jour avec la nouvelle date de fin renseignée.
Lire un ORCID Enregistrer (OBTENIR)
Revenez à l'onglet du navigateur pour Google Playground. Si vous n'avez pas laissé l'onglet ouvert, vous pouvez réinitialiser la session avec l'URL que vous avez enregistrée précédemment (en cliquant sur OK sur l'avertissement qui s'affiche). Ou vous pouvez configurer à nouveau l'appel en remplissant tous les champs pertinents, en vous assurant qu'ils ressemblent aux captures d'écran ci-dessous :
- Assurez-vous que le paramétrage a votre client ID et secret client
- Étape 2, vous devriez avoir votre jeton d'accès rempli
Il devrait toujours avoir le jeton du précédent ou vous pouvez le remplir à partir de l'exercice précédent comme ceci : - Étape 3 Cliquez Ajouter des en-têtes, entrez les valeurs ci-dessous, puis cliquez sur Ajouter et Fermé
- Nom de l'en-tête : Accepter
- Valeur d'en-tête : application/vnd.orcid+xml
- Les configurations de l'étape 3 devraient ressembler à la capture d'écran ci-dessous :
- Définissez la méthode HTTP sur ÉCONOMISEZ.
- Dans le champ URI de la requête saisissez :
https://api.sandbox.orcid.org/v3.0/0000-XXXX-XXXX-XXXX/record
Remplacer [ORCID ID] avec le iD pour votre enregistrement Sandbox, format XXXX-XXXX-XXXX-XXXX
Noter la point final est le mot à la fin de l'URI. Dans ce cas, nous lisons un résumé de l'ensemble de l'enregistrement, nous terminons donc l'URL par /record comme indiqué ci-dessus. - Cliquez Envoyez la demande
Dans le champ Requête/Réponse, vous devriez voir un résumé XML de l'ensemble de l'enregistrement. Cela ressemblera un peu à l'exemple ci-dessous qui montre la première partie de la réponse. Nous avons mis en évidence les codes put comme indiqué dans la section précédente
