Tutorial API: aggiungi e aggiorna i dati su un ORCID record

Puoi richiedi le credenziali dell'API membro sandbox per creare e testare la tua applicazione. Queste credenziali ti consentono di effettuare chiamate all'API del membro premium sandbox per leggere, scrivere e aggiornare ORCID record. L'accesso all'ambiente di test sandbox è disponibile gratuitamente per chiunque, anche se non sei un ORCID organizzazione membro.

Note:: Se stai utilizzando un ORCID sistema di fornitore di servizi certificato che già supporta ORCID, non è necessario registrarsi per ottenere le credenziali API sandbox a meno che non si desideri provare il ORCID funzionalità di integrazione all'interno dell'ambiente Sandbox. 

La sandbox ti consente di creare account utente di prova e sviluppare la tua integrazione senza doversi preoccupare di influenzare i dati sul live (produzione) ORCID Registro. La sandbox si comporta allo stesso modo della produzione ORCID Registro con alcune eccezioni.

Creazione di un account di prova

Per testare il ORCID API e chiamate API, come la lettura e l'aggiunta di informazioni a un file ORCID record, dovrai anche creare un test ORCID registrare nella sandbox. Questo può essere fatto tramite l'interfaccia utente, proprio come nella produzione ORCID Registro. Vai a https://sandbox.orcid.org/register e registrati per un account.

Indirizzi di posta elettronica

Il server sandbox invia solo email a Mailinator (@mailinator.com) indirizzi e-mail per non inviare spam ai server di posta involontariamente. Non riceverai un'e-mail di verifica o una notifica di reimpostazione della password a meno che tu non utilizzi un indirizzo @mailinator.com e la verifica è necessaria per apportare modifiche manuali ai record sandbox. Scopri di più sulle loro caselle di posta pubbliche gratuite Se non si desidera utilizzare a Mailinator indirizzo, quindi prendi nota del tuo nome utente e password (poiché li utilizzerai per concedere l'autorizzazione alla tua applicazione durante il test) e contattaci per richiedere assistenza con la verifica.

Mailinator è un servizio di posta elettronica che ha un servizio pubblico gratuito e un servizio privato a pagamento. Per i test è possibile utilizzare il servizio pubblico completamente gratuito. Scopri di più sui loro livelli qui.

Mailinator è un servizio di terze parti che non è gestito o mantenuto da ORCID. Ti consigliamo di rivedere il funzionamento di questo servizio e le sue limitazioni prima di utilizzare questi indirizzi.

Ci sono due diversi ambiti di aggiornamento: uno per i dettagli biografici, l'altro per le attività.

ORCID integrazioni utilizzano "OAuth a 3 vie" per autenticare gli utenti e richiedere l'autorizzazione per interagire con i loro record. Qualsiasi integrazione può richiedere autorizzazioni di lettura utilizzando l'API pubblica. ORCID i membri possono utilizzare l'API membro per richiedere autorizzazioni di aggiornamento. Funziona così:

• Crei un collegamento speciale
• Quando si fa clic, l'utente viene inviato a ORCID
  • ORCID chiede all'utente di accedere
  • ORCID chiede all'utente di concedere l'autorizzazione alla tua applicazione
  • ORCID rimanda l'utente al tuo sistema con un codice di autorizzazione
• Il tuo sistema scambia quel codice con un token di accesso

L'URL di autorizzazione personalizzato include le informazioni del tuo cliente, nonché gli "ambiti" che specificano le aree specifiche del suo record a cui desideri accedere. Dopo aver effettuato l'accesso, l'utente autorizza la connessione con il tuo sistema e viene reindirizzato alla tua pagina di destinazione insieme a un codice di autorizzazione. Questo codice viene quindi utilizzato per ottenere il loro file ORCID iD insieme a un token di accesso valido per gli ambiti richiesti.

Crea il link di autorizzazione e ottieni un codice di autorizzazione

Crei il tuo link di autorizzazione specificando il client delle tue credenziali API ID e pagina di destinazione associata (URI di reindirizzamento). Scegli tu quali permessi richiedere impostando il parametro di ambito.

L'esempio seguente richiede il permesso di leggere i dati ad accesso limitato sul ORCID server di test sandbox. Nel mondo reale visualizzi questo collegamento sul tuo sito web o lo includi in un'e-mail quando chiedi all'utente di autenticarsi e autorizzare. Tuttavia, a scopo di test puoi semplicemente incollarlo nel tuo browser web. Sostituisci i dati tra parentesi con le informazioni del tuo cliente e assicurati di rimuovere le parentesi quadre!

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

Una volta che l'utente ha fatto clic sul collegamento, ha effettuato l'accesso a ORCID e le autorizzazioni concesse vengono reindirizzate al tuo sito, in questo modo:

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

Scambiare il codice di autorizzazione con un ORCID iD e token di accesso

È necessario scambiare immediatamente il codice di autorizzazione per il ORCID iD e token di accesso. Il codice di autorizzazione scade al momento dell'uso. La richiesta è simile a questa e non può essere fatto in un browser web, deve essere creato dal tuo server.

 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 restituirà quindi l'autenticazione del ricercatore ORCID iD e un token di accesso in formato 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"}

I token di accesso sono di lunga durata per impostazione predefinita e scadono 20 anni dopo l'emissione. Il token può essere utilizzato più volte prima della scadenza.

Usa il token di accesso

I token di accesso a 3 gambe sono collegati a specifici ORCID documentazione. Per utilizzarli, includili nelle richieste API che effettui per leggere o aggiornare quel record.

Quando si richiede il permesso di interagire con an ORCID record dell'utente, si specifica uno o più 'scope'. Ciascun ambito consente di eseguire determinate operazioni, ad esempio leggere il record o aggiornare una determinata sezione.

Ambiti a 3 gambe (codice di autorizzazione)

3 gambe si riferisce ai tre attori coinvolti nell'ottenere il permesso da un utente; ORCID, il tuo sistema e l'utente stesso.

/autenticare

Questo ambito viene utilizzato per raccogliere i ORCID iD e leggere le informazioni pubbliche solo sul record. Tutti gli altri ambiti a 3 vie includono l'autorizzazione di autenticazione, quindi questo ambito può essere omesso se si richiede qualsiasi altro accesso. Questo ambito è disponibile nell'API Membro o Pubblica.

/read-limited (solo API membro)

Questo ambito viene utilizzato per ottenere l'accesso alla lettura di elementi pubblici e a visibilità limitata su un ORCID disco. Questo ambito è disponibile solo sull'API membro.

/activities/update (solo API per i membri)

Questo ambito viene utilizzato per scrivere, aggiornare ed eliminare elementi nelle sezioni di affiliazione, finanziamento, lavori, attività professionali, risorse di ricerca e revisione paritaria di un ORCID disco. Questo ambito è disponibile solo sull'API membro.

/person/update (solo API per i membri)

Questo ambito viene utilizzato per scrivere, aggiornare ed eliminare elementi nelle sezioni di altri nomi, parole chiave, paesi, URL dei ricercatori, siti Web e identificatori esterni personali del record. Questo ambito è disponibile solo sull'API membro.

OpenID

Questo ambito viene utilizzato dagli integratori OpenID quando è richiesto un id_token. Quando l'ambito openid è incluso, il registro restituirà un id_token all'interno della risposta del token e concederà al client l'autorizzazione per accedere all'endpoint delle informazioni utente per quell'utente. Questo ambito è disponibile nell'API pubblica e membro.

Si prega di notare che l'ambito 'openid' non inizia con una '/' come l'altro ORCID Ambiti API. Questo perché l'ambito 'openid' non è definito da ORCID, ma invece definito dalla specifica OpenID Connect. Si prega di consultare il nostro Documentazione OpenID per maggiori informazioni.

Scopi multipli Multiple

È possibile richiedere più ambiti in una singola interazione elencando gli ambiti nell'URL di autenticazione con uno spazio codificato tra ciascuno, ad esempio scope=/read-limited%20/activities/update%20/person/update

Accesso completo

Se desideri l'accesso completo per leggere e modificare un record, includi tre ambiti nell'URL di autenticazione: /read-limited, /activities/update e /person/update. Nell'URL apparirebbero come scope=/read-limited%20/activities/update%20/person/update

Ambiti a 2 vie (credenziali client)

Per alcune attività non è necessario chiedere il permesso all'utente. Gli ambiti OAuth a due vie sono richiesti direttamente dal ORCID API e non richiedono al ricercatore di concedere l'autorizzazione. I token con questi ambiti sono validi per 20 anni e possono essere riutilizzati

/leggi-pubblico

Questo ambito viene utilizzato per leggere le informazioni pubbliche su un singolo ORCID ID, cerca ORCID record o per leggere informazioni di riepilogo (solo API membro). Questo ambito è disponibile nell'API membro o pubblica.

/ webhook

Questo ambito consente a un'applicazione client di registrare un webhook su un ORCID record, per ricevere notifiche quando un record viene aggiornato. Questo ambito è disponibile per premium ORCID solo i membri.

Gli elementi (lavori, occupazione, finanziamenti, revisione paritaria, ecc.) possono essere aggiunti a un ORCID registrare utilizzando il ORCID API membro. Per fare questo, devi prima ottenere il permesso dal ricercatore utilizzando OAuth e formattare i metadati dell'elemento usando il ORCID schema del messaggio.

Dopo aver formattato i dati e raccolto il file ORCID iD e token di accesso, si effettua una richiesta API utilizzando HTTP POST, specificando il endpoint rilevante.

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

La chiamata qui sotto aggiunge una nuova occupazione affiliazione a un record sul server di test sandbox:

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

Esempio di chiamata: Github

L'API restituirà un messaggio 201 per indicare che l'articolo è stato pubblicato correttamente, insieme all'articolo metti il ​​codice. Il tuo cliente sarà elencato come il fonte dell'articolo.

Vai alla la risoluzione dei problemi pagina se viene restituito un messaggio diverso. Dovrai salvare il  memorizzare il codice put e il token di accesso per apportare eventuali aggiornamenti o rimuovere l'elemento.

An ORCID il record può contenere informazioni sul lavoro di un ricercatore, affiliazioni, finanziamenti, revisione paritaria e altro.

Articoli su ORCID i record possono essere suddivisi in asserzioni che collegano il ORCID Titolare di iD con un'attività o affiliazione. Queste affermazioni possono essere aggiunte a ORCID record dal ricercatore che possiede il record, o dai sistemi che il ricercatore ha autorizzato a farlo. Chiamiamo l'entità che ha aggiunto un'asserzione a an ORCID registra il file source.

Esempi

Seguendo i nostri principi di trasparenza e apertura, riteniamo che sia importante essere in grado di vedere la fonte dell'affermazione, ovvero chi aggiunge tali informazioni al registro. Ecco come lo facciamo:

1. Quando un ricercatore (o un suo delegato persona fidata) aggiunge un'affermazione al proprio verbale, ORCID registra automaticamente quella persona come fonte
2. Quando un sistema approvato dal ricercatore aggiunge un'asserzione a un record, ORCID registra automaticamente il proprietario del sistema (un ORCID membro) come fonte.

Mostriamo il nome della sorgente nell'interfaccia utente e lo rendiamo disponibile (con il suo identificatore univoco) nell'API:

Tuttavia, i flussi di lavoro delle informazioni di ricerca possono essere più complicati di così e la vera fonte di un'asserzione può essere oscurata involontariamente da un sistema che aggiunge un elemento per conto di una persona o di un altro sistema. Per garantire la trasparenza, dobbiamo distinguere tra chi ha creato il collegamento tra la persona e l'elemento e chi ha aggiunto l'elemento al record. Come sopra, chi aggiunge l'oggetto al ORCID il record è il source; chiunque crei la connessione tra il ORCID iD e l'oggetto è il origine dell'asserzione.

Per esempio:

1. Un ricercatore importa i dati nel proprio ORCID record da un sistema, ad esempio una procedura guidata di ricerca e collegamento. Il ricercatore sta facendo l'asserzione collegando il loro iD con l'oggetto, quindi sono i origine dell'asserzione; mentre il sistema è l'entità che aggiunge l'asserzione al ORCID registrare - il source
2. Un ricercatore interagisce con il Sistema A (il asserzione origin), che utilizza i servizi forniti dal Sistema B per aggiornare ORCID record, rendendo il sistema B il source

Incoraggiamo la nostra comunità a impegnarsi nell'adozione di misure per preservare e condividere le informazioni sull'origine dell'asserzione, in modo che tutti possano trarre vantaggio dal vedere la fonte.

Per ulteriori informazioni, si prega di consultare:

• Assertion Assurance Pathways: cosa sono e perché sono importanti?
• Piani per abilitare più asserzioni nel ORCID registro

ORCID i membri possono aggiornare le informazioni che hanno precedentemente aggiunto a un ORCID disco. È possibile aggiornare un solo elemento alla volta e può essere aggiornato solo utilizzando le credenziali del client che lo hanno creato in primo luogo.

Per facilitare l'aggiornamento, assicurati di memorizzare il codice put e il token di accesso durante la creazione di oggetti.

Formatta l'elemento aggiornato in ORCID schema del messaggio con le informazioni modificate e includere le informazioni memorizzate metti il ​​codice.

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

Chiama 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

Chiamate di esempio: GitHub

L'API restituirà un messaggio 200 OK per indicare che l'elemento è stato aggiornato correttamente. Controlla la nostra pagina di risoluzione dei problemi se viene restituito un messaggio diverso.

Tutti gli articoli (a parte il testo della biografia) su an ORCID il record ha un metti il ​​codice:

<?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>

Questo codice put può essere utilizzato per effettuare una chiamata all'API per recuperare i dati completi per un elemento. I seguenti elementi possono essere interrogati utilizzando a metti il ​​codice:

Utilizzando l'endpoint della sezione e il codice put, puoi chiamare l'API utilizzando lo stesso token di accesso per ottenere l'intero elemento specifico. Questa chiamata di esempio recupera l'elemento di finanziamento completo 4413 in formato XML utilizzando l'API membro sul server 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

Chiamata di esempio: GitHub

L'API restituirà un messaggio 200 OK per indicare che il messaggio è stato ricevuto correttamente e restituirà l'XML completo dell'elemento di finanziamento:

<?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>

È possibile controllare il fonte di un elemento quando lo leggi se vuoi sapere chi lo ha aggiunto.

Se hai aggiunto dati che devono essere eliminati, ad esempio, se sono stati associati a un errore ORCID iD, quindi puoi effettuare una richiesta DELETE HTTP specificando il endpoint pertinente, insieme con il ORCID ID, token di accesso memorizzato e codice put memorizzato. È possibile eliminare solo un elemento alla volta e puoi eliminare solo gli elementi aggiunti dal tuo cliente. È possibile eliminare elementi anche quando l'utente ha revocato l'autorizzazione.

Questa chiamata di esempio elimina l'elemento di occupazione con il codice put "739288" da un record"

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

Chiamata di esempio: GitHub

Si prega di consultare il nostro elenco di identificatori supportati per l'API V3.0. Occasionalmente aggiungiamo nuovi tipi su richiesta di ORCID membri che desiderano utilizzarli quando aggiungono elementi al registro.

ORCID supporta l'uso di  Identificatori ROR, Identificatori GRIGLIA e Registro dei finanziatori Crossref identificatori per disambiguare le organizzazioni in ORCID Records. 

Per ulteriori informazioni, vedere Lavorare con gli identificatori dell'organizzazione

Sebbene gli identificatori Ringgold esistano ancora all'interno del file ORCID registro, dal 1° agosto 2023, ORCID non riceverà più aggiornamenti al database degli identificatori dell'organizzazione RINGGOLD utilizzato dal nostro Registro, né saremo in grado di elaborare o utilizzare gli ID RINGGOLD creati dopo tale data. Vedi il nostro FAQ per maggiori informazioni

Lavori in ORCID sono raggruppati in base sia ai loro identificatori che a tali identificatori‚ in relazione all'opera. Esistono quattro tipi di relazioni:

• Auto: l'identificatore si riferisce esclusivamente a quell'opera e può essere raggruppato con altre opere che hanno lo stesso identificatore
• Parte di: l'opera fa parte di questo identificatore e non può essere raggruppata con altre opere
• Versione di: questi identificatori si applicano a versioni alternative dell'opera e possono essere raggruppati con sé e versione degli identificatori
• Fondato da: questi identificatori si applicano al finanziamento dell'opera. Questi identificatori non vengono utilizzati per raggruppare le opere.

La nostra API fornisce supporto per questo nell'XSD. Ogni elemento ha un attributo indice di visualizzazione che ne indica la posizione all'interno del relativo gruppo. L'indice di visualizzazione più alto è l'elemento preferito selezionato dal ricercatore. Gli elementi aggiunti tramite l'API che non sono stati classificati dal ricercatore hanno un indice di visualizzazione pari a 1 e vengono utilizzati come fonte preferita predefinita all'interno del gruppo finché non vengono modificati dal ricercatore. L'indice di visualizzazione determina anche l'ordine di lavoro durante la lettura del file ORCID registrare con l'API.

Per ulteriori informazioni sul raggruppamento su ORCID record, si prega di consultare il nostro articolo di supporto.

Visibilità indica l'impostazione della privacy dell'elemento, in base alla preferenza di visibilità impostata dall'utente. Se viene incluso un tag di visibilità quando le informazioni vengono pubblicate tramite l'API, verrà ignorato. Piuttosto, le informazioni verranno pubblicate in base alla preferenza di visibilità predefinita dell'utente come impostata nelle preferenze dell'account.

Gli elementi pubblici possono essere letti da chiunque tramite l'API e vengono visualizzati nel registro pubblico del ricercatore. Gli elementi di parti attendibili vengono restituiti tramite l'API solo ai client che hanno accesso limitato in lettura; non sono nel registro pubblico del ricercatore. Gli elementi privati ​​sono visibili solo al ricercatore e alla fonte dell'elemento: gli unici elementi privati ​​restituiti tramite l'API sono quelli che sono stati aggiunti al record tramite la tua integrazione Maggiori informazioni sulle impostazioni di visibilità in ORCID registro.

Ricevono una notifica nel loro ORCID Posta in arrivo. Ogni volta che c'è un cambiamento nei dati su un ORCID record, l'utente riceve una notifica con le informazioni di base sulla modifica, incluso il nome del cliente che esegue l'aggiornamento, la data della modifica e l'elemento nel ORCID record che è stato aggiornato. Guarda il nostro User Knowledge Base per ulteriori informazioni sulle notifiche.  

ORCID anche i record sulla sandbox hanno caselle di posta funzionanti. Ti consigliamo di controllare regolarmente le caselle di posta dei tuoi test ORCID record durante la pianificazione del modo in cui i sistemi pianificheranno gli aggiornamenti dei dati.