Tutorial API: leggere i dati su un record

Consigliamo agli sviluppatori di testare l'API pubblica nel server di test sandbox prima di utilizzare la versione di produzione. Di seguito sono riportati i passaggi su come registrarsi per le credenziali API pubbliche sia negli ambienti Sandbox che in quelli di produzione.

• Accedi al tuo ORCID disco:
  Server di produzione: https://orcid.org/signin
  Server di test sandbox: https://sandbox.orcid.org/signin
• Clicca sul tuo nome nell'angolo in alto a destra
• Clicchi Strumenti di sviluppo dall'opzione di menu
  Nota: Per accedere agli Strumenti per sviluppatori, devi verificare il tuo indirizzo email. Se non hai ancora verificato il tuo indirizzo email, ti verrà chiesto di farlo prima di poterti registrare per le credenziali API pubbliche
• Leggi e accetta il 'ORCID Termini di servizio del cliente pubblico
• Fai clic su "Registrati per ORCID credenziali API pubbliche”.

Completamento del modulo dei dettagli dell'applicazione

• Dopo esserti registrato per le tue credenziali API pubbliche, verrai reindirizzato a Strumenti per sviluppatori (https://orcid.org/developer-tools or https://sandbox.orcid.org/developer-tools).
• È necessario completare il modulo dei dettagli della domanda presentato per registrare una nuova domanda.
  • Nome: il nome della tua applicazione. Questo verrà mostrato agli utenti quando concedono alla tua applicazione l'autorizzazione per ottenere il loro ORCID iD, e verrà visualizzato nella loro Elenco delle organizzazioni affidabili. Ti consigliamo di utilizzare il nome della tua organizzazione o servizio (ad es. il nome di una rivista).
  • URL dell'applicazione: Il sito web che l'utente può visitare per saperne di più sulla tua applicazione. Questo verrà visualizzato anche nel loro Elenco delle organizzazioni affidabili.
  • Descrizione dell'applicazione: Informazioni sull'applicazione che stai sviluppando e su come utilizzerai le ORCID ID. Questo verrà mostrato agli utenti nella schermata OAuth.

Aggiunta URI di reindirizzamento

Una volta che l'utente ha autorizzato la tua applicazione, verrà restituito a un URI da te specificato. È necessario fornire questi URI in anticipo o gli utenti dell'integrazione riscontreranno un errore.

• Inserisci il tuo URI di reindirizzamento nella casella fornita
• Se devi inserire più di un URI di reindirizzamento, fai clic su "Aggiungi un altro URI di reindirizzamento"

Nota bene:

• Solo URI HTTPS sono accettati in produzione
• Domini registrati MUST corrispondono esattamente ai domini utilizzati, compresi i sottodomini
• Registra tutti gli URI di reindirizzamento completamente ove possibile. Questa è l'opzione più sicura e ciò che consigliamo. Per ulteriori informazioni sugli URI di reindirizzamento, consultare il nostro Domande frequenti sull'URI di reindirizzamento

Salvataggio della tua applicazione

Dopo aver completato il modulo di domanda e aver aggiunto i tuoi URI di reindirizzamento, puoi salvare la tua domanda.

• Fai clic su "Salva la mia domanda e genera il mio ID cliente e segreto"

Verrai reindirizzato alla pagina degli strumenti per sviluppatori che ora includerà le tue credenziali del client API pubblica

Aggiornamento delle tue credenziali

Apportare una modifica alle informazioni sulla tua domanda è molto semplice.

• Modifica le informazioni pertinenti e fai clic su "Salva domanda"

Usa le tue credenziali

Ora che hai le tue credenziali, è ora di iniziare a utilizzare il ORCID API pubblica!

Tieni presente che possiamo trasferire le tue credenziali all'API dei membri se diventi un ORCID membro in futuro.

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.

Chiunque disponga di credenziali API pubbliche o membro può ricevere un /leggi-pubblico token di accesso. Per ottenere un token, fai una chiamata al ORCID Endpoint del token API.

Questo processo viene spesso definito flusso OAuth delle credenziali client o OAuth in due passaggi.

Una chiamata di esempio per ottenere un token di accesso per leggere i dati pubblici sulla sandbox: sostituire i segnaposto con le proprie credenziali (assicurarsi di rimuovere le parentesi.

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

Ti verrà quindi restituito un token di accesso simile al seguente. Il token restituito è di lunga durata (non scade per circa 20 anni) e può essere utilizzato più volte per recuperare dati pubblici da 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}

Nota: Tutti i token con l'ambito /authenticate ora includono anche l'ambito /read-public. Se usi solo l'ambito /authenticate, puoi usare i token di accesso archiviati per leggere i dati pubblici senza dover ottenere nuovamente un token di accesso. 

Gli integratori che utilizzano l'API membro possono utilizzare il file /leggi-pubblico spazio per leggere ORCID registrare i riepiloghi.

Per ottenere l'accesso/lettura limitato, è necessario chiedere l'autorizzazione al ricercatore. Lo fai usando OAuth. Nello specifico, “OAuth a 3 zampe".

Per ulteriori informazioni, consultare il nostro Tutorial API: leggere i dati su un ORCID record

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

Puoi creare il tuo collegamento di autorizzazione specificando l'ID client delle tue credenziali API e la landing page associata (URI di reindirizzamento). Puoi scegliere quali autorizzazioni 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.

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.

Questa chiamata di esempio recupera un riepilogo dell'intero ORCID registrare in formato XML utilizzando l'API membro sul server sandbox. È necessario un token di accesso per effettuare richieste API all'API pubblica o membro.

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 restituirà un messaggio 200 OK, indicando che la richiesta è stata ricevuta con successo, e il riepilogo completo del ORCID registrazione, compresi i riepiloghi dei singoli elementi.

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

Ogni voce (lavoro, finanziamento, occupazione, ecc.) ha un metti il ​​codice. Questo può essere utilizzato per ottenere tutti i dettagli dell'articolo, se necessario.

La ORCID record è suddiviso in singole sezioni per rendere la lettura del record più veloce e coerente. Puoi prima chiamare una sezione per riceverne il riepilogo, quindi chiamare utilizzando il codice put di un singolo articolo per ricevere informazioni affidabili su quell'articolo.

Di seguito è riportata una tabella delle sezioni di riepilogo che è possibile leggere tramite l'API.

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.

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.

La ORCID registro supporta la "negoziazione dei contenuti". Ciò significa che macchine e altri sistemi possono chiedere ORCID registro per i metadati delle persone in diversi formati.

Uno di questi formati è JSON-LD, che utilizza il schema.org vocabolario, in particolare il tipo di persona, che colleghiamo a opere, organizzazioni e altri identificatori. Supportiamo anche XML, JSON, RDF XML e turtle e abbiamo implementato la condivisione di risorse cross-origin (CORS) per rendere i nostri dati facilmente accessibili.

• Vedere questa post sul blog per una panoramica di ORCID e schema.org
• vedere il nostro documentazione tecnica sulla negoziazione dei contenuti

Ricerca di un utente utilizzando cURL in questo modo:

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

Restituirà un 200 anche se l'utente non esistere. Per evitare ciò, usa la negoziazione del contenuto nella tua chiamata in questo modo:

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