Tutoriel API : Lire des données sur un enregistrement

Nous recommandons aux développeurs de tester l'API publique dans le serveur de test sandbox avant d'utiliser la version de production. Vous trouverez ci-dessous les étapes à suivre pour vous inscrire aux informations d'identification publiques de l'API dans les environnements Sandbox et Production.

• Connectez-vous à votre ORCID record:
  Serveur de production: https://orcid.org/signin
  Serveur de test Sandbox: https://sandbox.orcid.org/signin
• Cliquez sur votre nom dans le coin supérieur droit
• Cliquez Outils de développement à partir de l'option de menu
  Remarque : Pour accéder aux outils de développement, vous devez vérifier votre adresse e-mail. Si vous n'avez pas encore vérifié votre adresse e-mail, vous serez invité à le faire avant de pouvoir vous inscrire pour les informations d'identification de l'API publique
• Lisez et acceptez le 'ORCID Conditions d'utilisation du client public
• Cliquez sur "S'inscrire pour ORCID bouton d'informations d'identification de l'API publique ».

Remplir le formulaire de détails de la demande

• Une fois que vous vous êtes enregistré pour vos informations d'identification d'API publique, vous serez redirigé vers les outils de développement (https://orcid.org/developer-tools or https://sandbox.orcid.org/developer-tools).
• Vous devez remplir le formulaire de détails de candidature présenté pour enregistrer une nouvelle candidature.
  • Prénom: Le nom de votre application. Cela sera affiché aux utilisateurs lorsqu'ils accorderont à votre application l'autorisation d'obtenir leur ORCID iD, et il sera affiché dans leur Liste des organisations de confiance. Nous vous recommandons d'utiliser le nom de votre organisation ou service (par exemple, un nom de journal).
  • URL de l'application : Le site Web que l'utilisateur peut visiter pour en savoir plus sur votre application. Cela sera également affiché dans leur Liste des organisations de confiance.
  • Description de l'application: Informations sur l'application que vous développez et comment vous utiliserez les utilisateurs ORCID identifiant. Cela sera affiché aux utilisateurs sur l'écran OAuth.

L'ajout de Rediriger les URI

Une fois que l'utilisateur a autorisé votre application, il sera renvoyé à un URI que vous spécifiez. Vous devez fournir ces URI à l'avance, sinon vos utilisateurs d'intégration rencontreront une erreur.

• Entrez votre URI de redirection dans la case prévue
• Si vous devez saisir plus d'un URI de redirection, cliquez sur "Ajouter un autre URI de redirection".

Veuillez noter :

• Seulement URI HTTPS sont acceptés en production
• Domaines enregistrés DOIVENT correspondent exactement aux domaines utilisés, y compris les sous-domaines
• Enregistrez tous les URI de redirection dans la mesure du possible. C'est l'option la plus sûre et ce que nous recommandons. Pour plus d'informations sur les URI de redirection, veuillez consulter notre redirection URI FAQ

Enregistrement de votre candidature

Une fois que vous avez rempli le formulaire de candidature et ajouté vos URI de redirection, vous pouvez enregistrer votre candidature.

• Cliquez sur 'Enregistrer ma candidature et générer mon client ID et secrète'

Vous serez redirigé vers la page des outils de développement qui inclura désormais vos informations d'identification du client de l'API publique

Mise à jour de vos identifiants

Modifier les informations de votre candidature est très simple.

• Modifiez les informations pertinentes, puis cliquez sur "Enregistrer l'application"

Utilisez vos identifiants

Maintenant que vous avez vos identifiants, il est temps de commencer à utiliser le ORCID API publique!

Veuillez noter que nous pouvons transférer vos informations d'identification à l'API membre si vous devenez un ORCID membre dans le futur.

Vous pouvez demander les informations d'identification de l'API du membre du sandbox pour créer et tester votre application. Ces informations d'identification vous permettent d'appeler l'API du membre premium sandbox pour lire, écrire et mettre à jour ORCID records. L'accès à l'environnement de test du bac à sable est librement accessible à tous, même si vous n'êtes pas ORCID organisation membre.

Notes: Si vous utilisez un ORCID système de fournisseur de services certifié qui prend déjà en charge ORCID, vous n'avez pas besoin de vous inscrire pour obtenir les informations d'identification de l'API sandbox, sauf si vous souhaitez essayer le ORCID fonctionnalité d'intégration dans l'environnement Sandbox. 

Le bac à sable vous permet de créer des comptes utilisateurs de test et de développer votre intégration sans avoir à vous soucier d'affecter les données en direct (production) ORCID Enregistrement. Le bac à sable se comporte de la même manière que la production ORCID Registre avec quelques exceptions.

Créer un compte de test

Afin de tester le ORCID API et appels d'API, tels que la lecture et l'ajout d'informations à un ORCID record, vous devrez également créer un test ORCID enregistrer dans le bac à sable. Cela peut être fait via l'interface utilisateur, un peu comme sur la production ORCID Enregistrement. Aller à https://sandbox.orcid.org/register et inscrivez-vous pour un compte.

Adresses e-mail des expéditeurs

Le serveur sandbox envoie uniquement des e-mails à Mailinator (@mailinator.com) afin de ne pas spammer involontairement les serveurs de messagerie. Vous ne recevrez pas d'e-mail de vérification ni de notification de réinitialisation du mot de passe, sauf si vous utilisez une adresse @mailinator.com, et une vérification est nécessaire pour apporter des modifications manuelles aux enregistrements de bac à sable. En savoir plus sur leurs boîtes de réception publiques gratuites ici. Si vous ne souhaitez pas utiliser un Mailinator adresse, veuillez noter votre nom d'utilisateur et votre mot de passe (car vous les utiliserez pour autoriser votre application lors des tests), et contactez-nous pour demander de l'aide pour la vérification.

Mailinator est un service de messagerie qui dispose d'un service public gratuit et d'un service privé payant. Pour tester, vous pouvez utiliser le service public entièrement gratuit. En savoir plus sur leurs niveaux ici.

Mailinator est un service tiers qui n'est ni géré ni maintenu par ORCID. Nous vous recommandons d'examiner le fonctionnement de ce service et ses limites avant d'utiliser ces adresses.

Toute personne disposant d'informations d'identification API publiques ou membres peut recevoir un / read-public jeton d'accès. Pour obtenir un jeton, vous appelez le ORCID Point de terminaison du jeton API.

Ce processus est souvent appelé flux OAuth des informations d'identification du client ou OAuth en 2 étapes.

Un exemple d'appel pour obtenir un jeton d'accès pour lire les données publiques sur le bac à sable - remplacez les espaces réservés par vos informations d'identification (veillez à supprimer les crochets.

URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  METHOD: POST
  DATA: 
    client_id=[Your public API client ID]
    client_secret=[Your public API secret]
    grant_type=client_credentials
    scope=/read-public

Vous recevrez alors un jeton d'accès similaire au suivant. Le jeton renvoyé a une longue durée de vie (n'expirant pas pendant environ 20 ans) et peut être utilisé plusieurs fois pour récupérer des données publiques à partir de ORCID Records. 

{"access_token":"4bed1e13-7792-4129-9f07-aaf7b88ba88f","token_type":"bearer",
"refresh_token":"2d76d8d0-6fd6-426b-a017-61e0ceda0ad2","expires_in":631138518,
"scope":"/read-public","orcid":null}

Remarque : Tous les jetons avec l'étendue / authenticate ont maintenant également l'étendue / read-public incluse. Si vous utilisez uniquement l'étendue / authenticate, vous pouvez utiliser les jetons d'accès stockés pour lire les données publiques sans avoir à obtenir à nouveau un jeton d'accès. 

Les intégrateurs utilisant l'API membre peuvent utiliser le / read-public portée à lire ORCID enregistrer des résumés.

Pour obtenir un accès /limité en lecture, vous devez demander la permission au chercheur. Pour ce faire, utilisez OAuth. Spécifiquement, "OAuth à 3 étapes" .

Pour plus d'informations, veuillez consulter notre Tutoriel API : Lire des données sur un ORCID record

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 Member pour demander des autorisations de mise à jour. Cela fonctionne comme ceci :

• Vous créez un lien spécial
• Lorsqu'il clique dessus, l'utilisateur est envoyé vers ORCID
  • ORCID demande à l'utilisateur de se connecter
  • ORCID demande à l'utilisateur d'accorder l'autorisation à votre application
  • ORCID renvoie l'utilisateur à votre système avec un code d'autorisation
• Votre système échange ce code contre un jeton d'accès

L'URL d'autorisation personnalisée comprend les informations de votre client, ainsi que les « portées » qui spécifient les zones spécifiques de leur dossier auxquelles vous souhaitez accéder. Après s'être connecté, l'utilisateur autorise la connexion avec votre système et est renvoyé à votre page de destination avec un code d'autorisation. Ce code est ensuite utilisé pour obtenir leur ORCID iD ainsi qu'un jeton d'accès valide pour les étendues demandées.

Créez le lien d'autorisation et obtenez un code d'autorisation

Vous construisez votre lien d'autorisation en spécifiant le client de vos identifiants API ID et page de destination associée (URI de redirection). Vous choisissez les autorisations à demander en définissant le paramètre scope.

L'exemple ci-dessous demande l'autorisation de lire des données à accès limité sur le ORCID serveur de test sandbox. Dans le monde réel, vous affichez ce lien sur votre site Web ou l'incluez dans un e-mail lorsque vous demandez à l'utilisateur de s'authentifier et d'autoriser. Cependant, à des fins de test, vous pouvez simplement le coller dans votre navigateur Web. Remplacez les données entre crochets par les informations de votre client et assurez-vous de supprimer les crochets !

https://sandbox.orcid.org/oauth/authorize?client_id=[Your client ID]&response_type=code&scope=/read-limited&redirect_uri=[Your landing page]

Un utilisateur a cliqué sur le lien, connecté à ORCID et accordés des autorisations, ils sont redirigés vers votre site, comme ceci:

https://[Your landing page]?code=Q70Y3A

Échangez le code d'autorisation contre un ORCID iD et jeton d'accès

Vous devez immédiatement échanger le code d'autorisation pour le ORCID iD et jeton d'accès. Le code d'autorisation expire après utilisation. La demande ressemble à ceci et ne peut pas être effectué dans un navigateur Web, il doit être réalisé par votre serveur.

 URL=https://sandbox.orcid.org/oauth/token
  HEADER: Accept: application/json
  HEADER: Content-Type: application/x-www-form-urlencoded
  METHOD: POST
  DATA: 
    client_id=[Your client ID]
    client_secret=[Your client secret]
    grant_type=authorization_code
    code=Six-digit code
    redirect_uri=[Your landing page]

ORCID renverra alors le chercheur authentifié ORCID iD et un jeton d'accès au format JSON :

{"access_token":"f5af9f51-07e6-4332-8f1a-c0c11c1e3728","token_type":"bearer",
"refresh_token":"f725f747-3a65-49f6-a231-3e8944ce464d","expires_in":631138518,
"scope":"/read-limited","name":"Sofia Garcia","orcid":"0000-0001-2345-6789"}

Les jetons d'accès ont une longue durée de vie par défaut et expirent 20 ans après leur émission. Le jeton peut être utilisé plusieurs fois avant son expiration.

Utilisez le jeton d'accès

Les jetons d'accès à 3 pattes sont liés à des ORCID enregistrer. Pour les utiliser, vous les incluez dans les requêtes API que vous effectuez pour lire ou mettre à jour cet enregistrement.

La visibilité indique le paramètre de confidentialité de l'élément, en fonction des préférences de visibilité définies par l'utilisateur. Si une balise de visibilité est incluse lors de la publication d'informations via l'API, elle sera ignorée. Au lieu de cela, les informations seront publiées selon la préférence de visibilité par défaut de l'utilisateur définie dans les préférences de son compte.

Les éléments publics peuvent être lus par n'importe qui via l'API et sont affichés dans le dossier public du chercheur. Les éléments de confiance ne sont renvoyés via l'API qu'aux clients disposant d'un accès limité en lecture ; ils ne figurent pas dans le dossier public du chercheur. Les éléments privés ne sont visibles que par le chercheur et la source de l'élément. Les seuls éléments privés renvoyés via l'API sont ceux qui ont été ajoutés à l'enregistrement via votre intégration. En savoir plus sur les paramètres de visibilité dans le ORCID Registre .

Cet exemple d'appel récupère un résumé de l'intégralité ORCID enregistrement au format XML à l'aide de l'API membre sur le serveur sandbox. Vous avez besoin d'un jeton d'accès pour faire une demande d'API à l'API publique ou membre.

Method: GET Accept: application/vnd.orcid+xml
Authorization type and Access token: 
Bearer [Stored access token]
URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/record

L'API renverra un message 200 OK, indiquant que la demande a été reçue avec succès, et le résumé complet de la ORCID dossier, y compris les résumés des éléments individuels.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <record:record path="/0000-0001-2345-6789" xmlns:internal="https://www.orcid.org/ns/internal" [...]>
     <funding:funding-summary put-code="4413" path="/0000-0001-2345-6789/funding/4413" visibility="public" display-index="0">
  [...] 
  </record:record>

Chaque élément (travail, financement, emploi, etc.) a un mettre le code. Cela peut être utilisé pour obtenir tous les détails de l'article si nécessaire.

L' ORCID L'enregistrement est divisé en sections individuelles pour rendre la lecture de l'enregistrement plus rapide et plus cohérente. Vous pouvez d'abord appeler une section pour recevoir son résumé, puis appeler en utilisant le code de vente d'un élément individuel pour recevoir des informations fiables sur cet élément.

Un tableau des sections récapitulatives que vous pouvez lire à l'aide de l'API est présenté ci-dessous.

Tous les éléments (à l'exception du texte de la biographie) sur un ORCID enregistrement ont un mettre le code:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>   
<record:record path="/0000-0001-2345-6789" xmlns:internal="https://www.orcid.org/ns/internal" [...]>      
<funding:funding-summary put-code="4413" path="/0000-0001-2345-6789/funding/4413" visibility="public" display-index="0">   [...] 
</record:record>

Ce code put peut être utilisé pour appeler l'API afin de récupérer les données complètes d'un élément. Les éléments suivants peuvent être interrogés à l'aide d'un mettre le code:

À l'aide du point de terminaison de la section et du code put, vous pouvez appeler l'API à l'aide de votre même jeton d'accès pour obtenir l'intégralité de cet élément spécifique. Cet exemple d'appel récupère l'élément de financement complet 4413 au format XML à l'aide de l'API membre sur le serveur sandbox.

Method: GET Accept: application/vnd.orcid+xml Authorization type and Access token: Bearer [stored access token]URI: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/funding/4413

Exemple d'appel : GitHub

L'API renverra un message 200 OK pour indiquer que le message a été reçu avec succès et renverra le XML complet de l'élément de financement :

<?xml version="1.0"  encoding="UTF-8" standalone="yes"?>
    <funding:funding put-code="4413" path="/0000-0002-9227-8514/funding/4413" visibility="public"  [...] >
    [...] 
    </funding:funding>

Vous pouvez vérifier la provenance d'un article en le lisant si vous voulez savoir qui l'a ajouté.

Fonctionne ORCID sont regroupés en fonction à la fois de leurs identifiants et de la relation entre ces identifiants et l'œuvre. Il existe quatre types de relations :

• Soi: l'identifiant se réfère uniquement à cette œuvre et peut être regroupé avec d'autres œuvres qui ont le même identifiant
• Une partie de: l'œuvre fait partie de cet identifiant et ne peut être regroupée avec d'autres œuvres
• Version d': ces identifiants s'appliquent aux versions alternatives de l'œuvre et peuvent être regroupés avec soi et la version des identifiants
• Financé par: ces identifiants s'appliquent au financement des travaux. Ces identifiants ne sont pas utilisés pour le regroupement d'œuvres.

Notre API prend en charge cela dans le XSD. Chaque élément possède un attribut d'index d'affichage qui indique son rang au sein de son groupe. L'indice d'affichage le plus élevé est l'élément préféré sélectionné par le chercheur. Les éléments ajoutés via l'API qui n'ont pas été classés par le chercheur ont un indice d'affichage de 1 et sont utilisés comme source préférée par défaut au sein du groupe jusqu'à ce qu'ils soient modifiés par le chercheur. L'index d'affichage détermine également le bon de travail lors de la lecture du ORCID enregistrer avec l'API.

Pour plus d'informations sur le regroupement sur ORCID dossiers, veuillez consulter notre article de support.

L' ORCID le registre prend en charge la « négociation de contenu ». Cela signifie que les machines et autres systèmes peuvent demander ORCID registre pour les métadonnées de personne dans différents formats.

L'un de ces formats est JSON-LD, qui utilise le schema.org vocabulaire, en particulier le type de personne, que nous connectons avec des œuvres, des organisations et d'autres identifiants. Nous prenons également en charge XML, JSON, RDF XML et Turtle, et avons mis en œuvre le partage de ressources cross-origin (CORS) pour faciliter l'accès à nos données.

• Voir cette article de blog pour un aperçu de ORCID et schema.org
• Découvrez nos offres de documentation technique sur la négociation de contenu

Recherche d'un utilisateur à l'aide de cURL comme suit :

curl -iL https://orcid.org/0000-0000-0000-0000

Renverra un 200 même si l'utilisateur ne collecte exister. Pour éviter cela, utilisez la négociation de contenu dans votre appel comme suit :

curl -iL -H 'Accept: application/xml' https://orcid.org/0000-0000-0000-0000