Výukový program API: Přidat a aktualizovat data na ORCID záznam

Můžeš vyžádat si přihlašovací údaje člena API v karanténě k vytvoření a testování vaší aplikace. Tyto přihlašovací údaje vám umožňují volat do prémiového člena API sandboxu pro čtení, zápis a aktualizaci ORCID evidence. Přístup do testovacího prostředí karantény je volně k dispozici komukoli, i když nejste ORCID členské organizace.

Pozor: Pokud používáte ORCID certifikovaný systém poskytovatelů služeb, který již podporuje ORCID, nemusíte se registrovat pro přihlašovací údaje sandbox API, pokud si nepřejete vyzkoušet ORCID integrační funkce v rámci prostředí Sandbox. 

Sandbox umožňuje vytvářet testovací uživatelské účty a rozvíjet integraci, aniž byste se museli starat o ovlivnění dat naživo (produkce) ORCID Registr. Sandbox se chová stejně jako výroba ORCID Registrovat se několik výjimek.

Vytvoření testovacího účtu

Aby bylo možné otestovat ORCID API a volání API, jako je čtení a přidávání informací do souboru ORCID záznamu, budete také muset vytvořit test ORCID záznam v karanténě. To lze provést pomocí uživatelského rozhraní, podobně jako ve výrobě ORCID Registr. Jít do https://sandbox.orcid.org/register a zaregistrujte se pro účet.

Mailinátor e-mailové adresy

Sandbox server pouze odesílá e-maily Mailinator (@mailinator.com) e-mailové adresy, aby nedocházelo k nechtěnému spamování poštovních serverů. Pokud nepoužijete adresu @mailinator.com, neobdržíte ověřovací e-mail ani upozornění na resetování hesla a k provedení jakýchkoli ručních úprav záznamů v karanténě je vyžadováno ověření. Zjistěte více o jejich bezplatných veřejných schránkách zde. Pokud nechcete používat a Mailinator adresu, poznamenejte si prosím své uživatelské jméno a heslo (protože je budete používat k udělení autorizace vaší aplikaci při testování) a kontaktujte nás s žádostí o pomoc s ověřením.

Mailinator je e-mailová služba, která má veřejnou bezplatnou službu a soukromou placenou službu. Pro testování můžete využít zcela bezplatnou veřejnou službu. Zjistěte více o jejich úrovních zde.

Mailinator je služba třetí strany, kterou nespravuje ani nespravuje ORCID. Před použitím těchto adres doporučujeme zkontrolovat, jak tato služba funguje a její omezení.

Existují dva různé rozsahy aktualizací - jeden pro biografické podrobnosti a druhý pro aktivity.

ORCID integrace používají „3 legged OAuth“ k ověření uživatelů a vyžádání povolení k interakci s jejich záznamy. Jakákoli integrace může požádat o oprávnění ke čtení pomocí Public API. ORCID členové mohou pomocí Member API požádat o oprávnění k aktualizaci. Funguje to takto:

• Vytvoříte speciální odkaz
• Po kliknutí je uživatel odeslán na adresu ORCID
  • ORCID požádá uživatele o přihlášení
  • ORCID požádá uživatele o udělení povolení vaší aplikaci
  • ORCID odešle uživatele zpět do vašeho systému s autorizačním kódem
• Váš systém vymění tento kód za přístupový token

Přizpůsobená autorizační adresa URL obsahuje informace o vašem klientovi a také „rozsahy“, které určují konkrétní oblasti jejich záznamu, ke kterým chcete mít přístup. Po přihlášení uživatel autorizuje spojení s vaším systémem a je vrácen na vaši vstupní stránku spolu s autorizačním kódem. Tento kód je pak použit k jejich získání ORCID iD spolu s přístupovým tokenem platným pro požadované obory.

Vytvořte autorizační odkaz a získejte a autorizační kód

Autorizační odkaz vytvoříte zadáním ID klienta vašich pověření API a související vstupní stránky (URI přesměrování). Nastavením si zvolíte, o která oprávnění chcete požádat parametr oboru.

Níže uvedený příklad požaduje povolení ke čtení dat s omezeným přístupem na webu ORCID testovací server sandbox. Ve skutečném světě zobrazíte tento odkaz na své webové stránce nebo jej zahrnete do e-mailu, když uživatele požádáte o ověření a autorizaci. Pro účely testování jej však můžete jednoduše vložit do webového prohlížeče. Nahraďte data v závorkách informacemi o vašem klientovi a nezapomeňte odstranit hranaté závorky!

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

Jeden uživatel klikl na odkaz a přihlásil se na ORCID a udělená oprávnění jsou přesměrováni zpět na váš web, například takto:

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

Vyměňte autorizační kód za ORCID iD a přístupový token

Okamžitě byste měli vyměnit autorizační kód za ORCID iD a přístupový token. Platnost autorizačního kódu vyprší po použití. Žádost vypadá takto a nelze provést ve webovém prohlížeči, musí být provedeno vaším serverem.

 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 poté vrátí ověřeného výzkumného pracovníka ORCID iD a přístupový token ve formátu 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"}

Ve výchozím nastavení mají přístupové tokeny dlouhou životnost a jejich platnost vyprší 20 let po vydání. Token lze použít několikrát, než vyprší jeho platnost.

Použijte přístupový token

Třínohé přístupové tokeny jsou propojeny s konkrétními ORCID záznam. Chcete-li je používat, musíte je zahrnout do požadavků API, které provedete za účelem čtení nebo aktualizace daného záznamu.

Při žádosti o povolení k interakci s ORCID záznam uživatele, určíte jeden nebo více „oborů“. Každý obor umožňuje provádět určité věci, například číst záznam nebo aktualizovat konkrétní část.

Třínohé (autorizační kód) obory

3 nohy odkazuje na tři aktéry zapojené do získávání povolení od uživatele; ORCID, váš systém a samotný uživatel.

/ověřit

Tento rozsah se používá ke shromažďování ORCID iD a číst veřejné informace pouze na záznamu. Všechny ostatní obory se třemi nohami obsahují oprávnění k ověření, takže tento rozsah lze vynechat, pokud požadujete jakýkoli jiný přístup. Tento obor je k dispozici na členské nebo veřejné API.

/ read-limited (pouze členské rozhraní API)

Tento obor se používá k získání přístupu ke čtení veřejných a omezeně viditelných položek na ORCID záznam. Tento obor je k dispozici pouze v rozhraní API člena.

/ activities / update (pouze členské rozhraní API)

Tento rozsah se používá k zápisu, aktualizaci a mazání položek v sekcích přidružení, financování, prací, odborných činností, výzkumných zdrojů a odborných posudků ORCID záznam. Tento obor je k dispozici pouze v rozhraní API člena.

/ osoba / aktualizace (pouze členské rozhraní API)

Tento obor se používá k zápisu, aktualizaci a mazání položek v jiných částech záznamu, klíčových slov, zemí, výzkumných adres, webů a osobních externích identifikátorů. Tento obor je k dispozici pouze v rozhraní API člena.

otevřený

Tento obor používají integrátoři OpenID, když je vyžadován id_token. Když je zahrnut rozsah openid, registr vrátí id_token uvnitř odpovědi tokenu a udělí klientovi oprávnění pro přístup k koncovému bodu s informacemi o uživateli pro daného uživatele. Tento obor je k dispozici na veřejné a členské API.

Pamatujte, že obor „openid“ nezačíná znakem „/“ jako ten druhý ORCID Rozsahy API. Je to proto, že obor „openid“ není definován ORCID, ale místo toho definováno specifikací OpenID Connect. Přečtěte si prosím naše Dokumentace OpenID Pro více informací.

Více oborů

V rámci jedné interakce lze požádat o více oborů tak, že seznamy oborů uvedete v ověřovací adrese URL s kódovaným prostorem mezi nimi, například scope = / read-limited% 20 / activities / update% 20 / person / update

Kompletní přístup

Pokud chcete plný přístup ke čtení a úpravám záznamu, zahrňte do své ověřovací adresy URL tři obory: / read-limited, / activities / update a / person / update. V adrese URL by se zobrazily jako scope = / read-limited% 20 / activities / update% 20 / person / update

Dvounohé (pověření klienta) obory

U některých činností nemusíte uživatele žádat o povolení. Dvounohé obory OAuth jsou požadovány přímo z ORCID API a nevyžadují, aby výzkumný pracovník udělil povolení. Tokeny s těmito obory jsou platné po dobu 20 let a lze je znovu použít

/ veřejné čtení

Tento obor se používá ke čtení veřejných informací na jednom ORCID iD, vyhledejte ORCID záznamy nebo ke čtení souhrnných informací (pouze pro členské API). Tento rozsah je dostupný na Member nebo Public API.

/ webhook

Tento obor umožňuje klientské aplikaci zaregistrovat webhook na ORCID záznam, aby bylo možné přijímat oznámení o aktualizaci záznamu. Tento obor je k dispozici prémiovému ORCID pouze členové.

Položky (práce, zaměstnání, financování, vzájemné hodnocení atd.) Lze přidat do ORCID záznam pomocí ORCID členské API. Chcete-li to provést, musíte nejprve získat povolení od výzkumníka pomocí OAuth si naformátovat metadata položky s použitím ORCID schéma zprávy.

Jakmile naformátujete data a shromáždíte je ORCID iD a přístupový token, vytvoříte požadavek API pomocí HTTP POST se specifikací relevantní koncový bod.

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

Volání níže přidává nový zaměstnání přidružení k záznamu na testovacím serveru karantény:

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

Příklad volání: Github

Rozhraní API vrátí zprávu 201, která označuje, že položka byla odeslána správně spolu s položkou vložte kód. Váš klient bude uveden jako zdroj položky.

Podívejte se na náš Řešení problémů stránka, pokud je vrácena jiná zpráva. Budete muset uložit  uložte put kód a přístupový token provádět jakékoli aktualizace nebo odebrat položku.

An ORCID Záznam může obsahovat informace o práci výzkumného pracovníka, přidružení, financování, vzájemném hodnocení a další.

Položky zapnuty ORCID záznamy lze rozdělit na tvrzení které spojují ORCID Držitel iD s aktivitou nebo přidružením. Tato tvrzení lze přidat do ORCID záznam provedený výzkumným pracovníkem, který záznam vlastní, nebo systémy, k nimž výzkumný pracovník udělil povolení. Říkáme entitě, která přidala tvrzení k ORCID zaznamenat zdroj.

Příklady

V souladu s našimi zásadami transparentnosti a otevřenosti se domníváme, že je důležité vidět zdroj tvrzení - kdo tyto informace do záznamu přidává. Takto to děláme:

1. Když výzkumný pracovník (nebo jejich pověřený důvěryhodný jedinec) přidává k jejich záznamu tvrzení, ORCID automaticky zaznamená tuto osobu jako zdroj
2. Když systém schválený výzkumníkem přidá tvrzení k záznamu, ORCID automaticky zaznamená vlastníka systému (an ORCID člen) jako zdroj.

Zobrazíme název zdroje v uživatelském rozhraní a zpřístupníme jej (s jeho jedinečným identifikátorem) v API:

Pracovní postupy výzkumu informací však mohou být komplikovanější a skutečný zdroj tvrzení může být neúmyslně zakryt tím, že jeden systém přidá položku jménem osoby nebo jiného systému. Abychom zajistili transparentnost, musíme rozlišovat mezi tím, kdo vytvořil spojení mezi osobou a položkou, a kdo přidal položku do záznamu. Jak je uvedeno výše, kdokoli přidá položku do ORCID záznam je zdroj; kdokoli vytvoří spojení mezi ORCID iD a položka je původ tvrzení.

Například:

1. Výzkumník importuje data do svých ORCID záznam ze systému, například z Průvodce vyhledáváním a propojením. Výzkumník dělá tvrzení spojující jejich iD s položkou, takže jsou původ tvrzení; zatímco systém je entita přidávající tvrzení do ORCID záznam - zdroj
2. Výzkumník interaguje se systémem A (dále jen "systém") tvrzení origi), který k aktualizaci využívá služby poskytované systémem B. ORCID záznamy, díky čemuž je systém B zdroj

Doporučujeme naší komunitě, aby se zapojila do kroků k uchování a sdílení informací o původu tvrzení, aby každý mohl mít prospěch z vidění zdroje.

Pro více informací, naleznete na:

• Cesty k zajištění tvrzení: Co jsou zač a proč jsou důležité?
• Plány pro povolení více tvrzení v systému Windows ORCID registr

ORCID členové mohou aktualizovat informace, které dříve přidali do souboru ORCID záznam. Najednou lze aktualizovat pouze jednu položku a lze ji aktualizovat pouze pomocí přihlašovacích údajů klienta, které ji vytvořily.

Chcete-li usnadnit aktualizaci, ujistěte se uložte put kód a přístupový token při vytváření položek.

Naformátujte aktualizovanou položku in ORCID schéma zprávy se změněnými informacemi a zahrnout uložené vložte kód.

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

Volejte 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

Příklad volání: GitHub

API vrátí zprávu 200 OK, která označuje, že se položka aktualizovala správně. Pokud se zobrazí jiná zpráva, podívejte se na naši stránku pro řešení potíží.

Všechny položky (kromě textu životopisu) na ORCID záznam mít vložte kód:

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

Tento put kód lze použít k volání rozhraní API k načtení úplných dat položky. Následující položky lze dotazovat pomocí a vložte kód:

Pomocí koncového bodu sekce a vloženého kódu můžete volat API pomocí stejného přístupového tokenu a získat tak konkrétní položku v plném rozsahu. Toto příkladové volání načte plnou položku financování 4413 ve formátu XML pomocí členské API na izolovaném serveru.

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

Příklad volání: GitHub

Rozhraní API vrátí zprávu 200 OK, což znamená, že zpráva byla úspěšně přijata, a vrátí úplné XML položky financování:

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

Můžete zkontrolovat zdroj položky při čtení chcete vědět, kdo ji přidal.

Pokud jste přidali data, která je třeba odstranit, například pokud byla spojena s nesprávným ORCID iD, pak můžete provést požadavek HTTP DELETE specifikující relevantní koncový bod, spolu s ORCID ID, uložený přístupový token a uložený put kód. Najednou lze odstranit pouze jednu položku a můžete odstranit pouze položky přidané vaším klientem. Položky můžete odstranit, i když uživatel odvolal oprávnění.

Toto ukázkové volání odstraní položku zaměstnání s kódem put „739288“ ze záznamu “

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

Příklad volání: GitHub

Přečtěte si prosím naše seznam podporovaných identifikátorů pro V3.0 API. Příležitostně přidáváme nové typy na žádost ORCID členové, kteří by je chtěli použít při přidávání položek do registru.

ORCID podporuje použití  Identifikátory ROR, Identifikátory GRID si Registr křížového funderu identifikátory k nejednoznačnosti organizací v EU ORCID evidence. 

Pro více informací viz Práce s identifikátory organizace

Přestože Ringgold identifikátory stále existují v rámci ORCID registru od 1. srpna 2023, ORCID již nedostává aktualizace databáze identifikátorů organizace RINGGOLD používané naším registrem, ani nebudeme moci zpracovávat nebo používat ID RINGGOLD vytvořené po tomto datu. Podívejte se na naše Nejčastější dotazy pro více informací

Pracuje v ORCID jsou seskupeny na základě jejich identifikátorů a vztahu těchto identifikátorů k dílu. Existují čtyři typy vztahů:

• Vlastní: identifikátor odkazuje pouze na toto dílo a lze jej seskupit s jinými pracemi, které mají stejný identifikátor
• Část: práce je součástí tohoto identifikátoru a nelze ji seskupit s jinými pracemi
• Verze: tyto identifikátory platí pro alternativní verze díla a lze je seskupit podle sebe a verze identifikátorů
• Financován: tyto identifikátory se vztahují na financování díla. Tyto identifikátory se nepoužívají pro seskupování děl.

Naše API pro to poskytuje podporu v XSD. Každá položka má atribut index zobrazení, který udává její pořadí v rámci skupiny. Nejvyšší index zobrazení je preferovaná položka vybraná výzkumníkem. Položky přidané prostřednictvím rozhraní API, které výzkumník nehodnotil, mají index zobrazení 1 a používají se jako výchozí preferovaný zdroj ve skupině, dokud je výzkumník nezmění. Index zobrazení také určuje pracovní pořadí při čtení ORCID záznam pomocí API.

Další informace o seskupování na ORCID záznamy, viz naše článek podpory.

Viditelnost označuje nastavení ochrany osobních údajů položky na základě preferencí viditelnosti nastavených uživatelem. Pokud je při zveřejňování informací prostřednictvím rozhraní API zahrnuta značka viditelnosti, bude ignorována. Místo toho budou informace zveřejňovány podle výchozí preference viditelnosti uživatele, jak je nastavena v předvolbách jeho účtu.

Veřejné položky může číst kdokoli prostřednictvím rozhraní API a jsou zobrazeny ve veřejném záznamu výzkumníka. Položky důvěryhodných stran se prostřednictvím rozhraní API vracejí pouze klientům, kteří mají přístup s omezeným čtením; nejsou ve veřejném záznamu výzkumníka. Soukromé položky jsou viditelné pouze pro výzkumníka a zdroj položky – jediné soukromé položky vrácené přes API jsou ty, které byly přidány do záznamu prostřednictvím vaší integrace Další informace o nastavení viditelnosti v ORCID registr.

Obdrží oznámení v jejich ORCID Doručená pošta. Kdykoli dojde ke změně dat na ORCID záznamu, uživatel obdrží oznámení se základními informacemi o změně, včetně jména klienta provádějícího aktualizaci, data změny a položky v ORCID záznam, který byl aktualizován. Podívejte se na naše uživatelská znalostní databáze pro více informací o oznámeních.  

ORCID záznamy na pískovišti také mají fungující schránky. Doporučujeme pravidelně procházet složky doručené pošty vašeho testování ORCID záznamy při plánování, jak budou vaše systémy plánovat aktualizace dat.