Tutoriel API : Ajouter et mettre à jour des données sur un ORCID record

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.

Il existe deux portées de mise à jour différentes - une pour les détails biographiques, l'autre pour les activités.

ORCID Les intégrations utilisent « OAuth à trois é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 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 d'accueil 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 créez votre lien d'autorisation en spécifiant l'ID client de vos informations d'identification API et la 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 lors de son utilisation. La requête 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 enregistrement. Pour les utiliser, vous les incluez dans les requêtes API que vous faites pour lire ou mettre à jour cet enregistrement.

Lorsque vous demandez l'autorisation d'interagir avec un ORCID l'enregistrement de l'utilisateur, vous spécifiez une ou plusieurs « étendues ». Chaque étendue vous permet de faire certaines choses, comme lire l'enregistrement ou mettre à jour une section particulière.

Portées à 3 branches (code d'autorisation)

3 patte désigne les trois acteurs impliqués dans l'obtention de l'autorisation d'un utilisateur ; ORCID, votre système et l'utilisateur lui-même.

/authentifier

Ce périmètre est utilisé pour collecter les ORCID iD et lire les informations publiques sur le dossier uniquement. Toutes les autres étendues à 3 branches incluent l'autorisation d'authentification, cette étendue peut donc être omise si vous demandez un autre accès. Cette portée est disponible sur l'API membre ou publique.

/read-limited (API membre uniquement)

Cette étendue est utilisée pour accéder à la lecture des éléments publics et à visibilité limitée sur un ORCID enregistrer. Ce champ d'application n'est disponible que sur l'API Member.

/activities/update (API membre uniquement)

Ce périmètre permet d'écrire, de mettre à jour et de supprimer des éléments dans les sections affiliation, financement, travaux, activités professionnelles, ressources de recherche et évaluation par les pairs d'un ORCID enregistrer. Ce champ d'application n'est disponible que sur l'API Member.

/person/update (API membre uniquement)

Cette portée est utilisée pour écrire, mettre à jour et supprimer des éléments dans les sections autres noms, mots-clés, pays, URL de recherche, sites Web et identifiants externes personnels de l'enregistrement. Ce champ d'application n'est disponible que sur l'API Member.

ouvert

Cette portée est utilisée par les intégrateurs OpenID lorsqu'un id_token est requis. Lorsque la portée openid est incluse, le registre renvoie un id_token dans la réponse du jeton et accorde au client l'autorisation d'accéder au point de terminaison des informations utilisateur pour cet utilisateur. Cette portée est disponible sur l'API publique et membre.

Veuillez noter que la portée 'openid' ne commence pas par un '/' comme les autres ORCID Portées de l'API. Ceci est dû au fait que la portée 'openid' n'est pas définie par ORCID, mais défini à la place par la spécification OpenID Connect. Veuillez consulter notre Documentation OpenID pour plus d'information.

Portées multiples

Plusieurs étendues peuvent être demandées en une seule interaction en répertoriant les étendues dans l'URL d'authentification avec un espace encodé entre chacune, comme scope=/read-limited%20/activities/update%20/person/update

Accès complet

Si vous souhaitez un accès complet pour lire et modifier un enregistrement, incluez trois étendues dans votre URL d'authentification : /read-limited, /activities/update et /person/update. Dans l'URL, ils apparaîtraient sous la forme scope=/read-limited%20/activities/update%20/person/update

Portées à deux branches (informations d'identification client)

Pour certaines activités, vous n'avez pas besoin de demander la permission à l'utilisateur. Les champs d'application OAuth à deux branches sont demandés directement à partir du ORCID API et ne nécessitent pas l'autorisation du chercheur. Les tokens avec ces portées sont valables 20 ans et peuvent être réutilisés

/ read-public

Cette portée est utilisée pour lire des informations publiques sur un seul ORCID ID, rechercher ORCID enregistrements ou pour lire des informations récapitulatives (API membre uniquement). Cette portée est disponible sur l'API membre ou publique.

/ webhook

Cette étendue permet à une application cliente d'enregistrer un webhook sur un ORCID enregistrement, afin de recevoir des notifications lorsqu'un enregistrement est mis à jour. Cette portée est disponible pour premium ORCID membres seulement.

Des éléments (travaux, emploi, financement, évaluation par les pairs, etc.) peuvent être ajoutés à un ORCID enregistrer en utilisant le ORCID API membre. Pour ce faire, vous devez d'abord obtenir la permission du chercheur en utilisant OAuth et formater les métadonnées de l'élément en utilisant l' ORCID schéma des messages.

Une fois que vous avez formaté les données et collecté les ORCID iD et le jeton d'accès, vous effectuez une requête API à l'aide de HTTP POST, en spécifiant le point final pertinent.

Method: POST 
Content-type: application/vnd.orcid+xml or application/vnd.orcid+json
Authorization type and Access token: Bearer [stored access token]data: link to file or text of single employment item to add 
URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/employment

L'appel ci-dessous ajoute une nouvelle emploi affiliation à un enregistrement sur le serveur de test sandbox :

<?xml version="1.0" encoding="UTF-8"?>      
<employment:employment [...]>     
[...]            
</employment:employment>

Exemple d'appel : Github

L'API renverra un message 201 pour indiquer que l'article a été publié correctement, ainsi que l'article mettre le code. Votre client sera répertorié comme le provenance de l'article.

Visitez notre dépannage page si un message différent est renvoyé. Vous devrez sauvegarder le  stocker le code d'accès et le jeton d'accès pour effectuer des mises à jour ou supprimer l'élément.

An ORCID Le dossier peut contenir des informations sur le travail d'un chercheur, ses affiliations, son financement, son évaluation par les pairs, etc.

Articles sur ORCID les enregistrements peuvent être décomposés en affirmations qui relient le ORCID titulaire d'une carte d'identité avec une activité ou une affiliation. Ces affirmations peuvent être ajoutées à un ORCID par le chercheur propriétaire du document ou par des systèmes que le chercheur a autorisé à le faire. Nous appelons l'entité qui a ajouté une assertion à un ORCID enregistrer le source.

Exemples

Conformément à nos principes de transparence et d'ouverture, nous pensons qu'il est important de pouvoir voir la source de l'affirmation - qui ajoute cette information au dossier. Voici comment nous procédons :

1. Lorsqu'un chercheur (ou son délégué personne de confiance) ajoute une assertion à son dossier, ORCID enregistre automatiquement cette personne comme source
2. Lorsqu'un système approuvé par le chercheur ajoute une assertion à un enregistrement, ORCID enregistre automatiquement le propriétaire du système (un ORCID membre) comme source.

Nous affichons le nom de la source dans l'interface utilisateur et le rendons disponible (avec son identifiant unique) dans l'API :

Cependant, les flux de travail d'informations de recherche peuvent être plus compliqués que cela, et la source réelle d'une affirmation peut être involontairement masquée par un système ajoutant un élément au nom d'une personne ou d'un autre système. Pour garantir la transparence, nous devons faire la distinction entre qui a établi le lien entre la personne et l'élément, et qui a ajouté l'élément à l'enregistrement. Comme ci-dessus, celui qui ajoute l'élément au ORCID l'enregistrement est le source; celui qui crée le lien entre le ORCID iD et l'article est le origine de l'affirmation.

Par exemple :

1. Un chercheur importe des données dans son ORCID enregistrement à partir d'un système, tel qu'un assistant de recherche et de lien. Le chercheur fait l'affirmation reliant leurs iD avec l'article, ils sont donc les origine de l'assertion; tandis que le système est l'entité qui ajoute l'assertion à la ORCID enregistrer — le source
2. Un chercheur interagit avec le système A (le affirmation originale), qui utilise les services fournis par le système B pour mettre à jour ORCID enregistrements, faisant du système B le source

Nous encourageons notre communauté à s'engager à prendre des mesures pour préserver et partager les informations sur l'origine de l'assertion, afin que tout le monde puisse bénéficier de voir la source.

Pour plus d'informations, s'il vous plaît voir:

• Parcours d'assurance d'assertion : que sont-ils et pourquoi sont-ils importants ?
• Plans d'activation des assertions multiples dans le ORCID Registre

ORCID les membres peuvent mettre à jour les informations qu'ils ont précédemment ajoutées à un ORCID enregistrer. Un seul élément peut être mis à jour à la fois, et il ne peut être mis à jour qu'à l'aide des informations d'identification client qui l'ont créé en premier lieu.

Pour faciliter la mise à jour, assurez-vous stocker le code d'accès et le jeton d'accès lors de la création d'éléments.

Formater l'élément mis à jour in ORCID schéma de message avec les informations modifiées et inclure les mettre le code.

<?xml version="1.0" encoding="UTF-8"?>      <employment:employment put-code="739288" [...]>     [...]            </employment:employment>

Appelez l'API :

Method: PUT Content-type: application/vnd.orcid+xml or application/vnd.orcid+jsonnAuthorization type and Access token: Bearer [stored access token]Data: link to file or text of affiliation to update URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/employment/739288

Exemples d'appels : GitHub

L'API renverra un message 200 OK pour indiquer que l'élément a été mis à jour correctement. Consultez notre page de dépannage si un message différent est renvoyé.

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é.

Si vous avez ajouté des données qui doivent être supprimées, par exemple, si elles ont été associées au mauvais ORCID iD, alors vous pouvez faire une requête HTTP DELETE en spécifiant le paramètre pertinent, avec le ORCID identifiant, jeton d'accès stocké et code de mise stocké. Un seul élément peut être supprimé à la fois et vous ne pouvez supprimer que les éléments ajoutés par votre client. Vous pouvez supprimer des éléments même lorsque l'utilisateur a révoqué l'autorisation.

Cet exemple d'appel supprime l'élément d'emploi avec le code de vente « 739288 » d'un enregistrement »

Method: DELETE 
Content-type:  application/vnd.orcid+xml or application/vnd.orcid+json
Authorization type and Access token: Bearer [stored access token]
URL: https://api.sandbox.orcid.org/v3.0/[ORCID iD]/employment/739288

Exemple d'appel : GitHub

Veuillez consulter notre liste des identifiants pris en charge pour l'API V3.0. Nous ajoutons occasionnellement de nouveaux types à la demande de ORCID membres qui souhaitent les utiliser lors de l'ajout d'éléments au registre.

ORCID soutient l'utilisation de  Identifiants ROR, Identifiants GRID et Registre des bailleurs de fonds Crossref identifiants pour lever l'ambiguïté des organisations dans ORCID Records. 

Pour plus d'informations, voir Utilisation des identifiants d'organisation

Bien que les identifiants Ringgold existent toujours au sein du ORCID registre, à compter du 1er août 2023, ORCID ne reçoit plus de mises à jour de la base de données d'identifiants d'organisation RINGGOLD utilisée par notre registre, et nous ne pourrons pas non plus traiter ou utiliser les identifiants RINGGOLD créés après cette date. Voir notre QFP pour plus d'informations

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.

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 partie 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 .

Ils reçoivent une notification dans leur ORCID boîte de réception. Chaque fois qu'il y a un changement dans les données d'un ORCID enregistrement, l'utilisateur reçoit une notification avec des informations de base sur le changement, y compris le nom du client effectuant la mise à jour, la date du changement et l'élément dans le ORCID enregistrement qui a été mis à jour. Voir notre base de connaissances utilisateur pour en savoir plus sur les notifications.  

ORCID les enregistrements sur le bac à sable ont également boîtes de réception fonctionnelles. Nous vous recommandons de parcourir régulièrement les boîtes de réception de vos tests ORCID enregistrements lors de la planification de la façon dont vos systèmes planifieront les mises à jour des données.