Výukový program API: Čtení dat na záznamu

Vývojářům doporučujeme otestovat veřejné API v sandbox testovací server před použitím produkční verze. Níže jsou uvedeny kroky, jak se zaregistrovat pro veřejné pověření API v prostředí Sandbox i Production.

• Přihlaste se do svého ORCID záznam:
  Produkční server: https://orcid.org/signin
  Testovací server izolovaného prostoru: https://sandbox.orcid.org/signin
• Klikněte na své jméno v pravém horním rohu
• klikněte Vývojářské nástroje z možnosti nabídky
  Poznámka: Chcete-li získat přístup k nástrojům pro vývojáře, musíte ověřit svou e-mailovou adresu. Pokud jste ještě neověřili svou e-mailovou adresu, budete vyzváni, abyste tak učinili, než se budete moci zaregistrovat pro veřejné přihlašovací údaje API
• Přečtěte si a souhlasíte s 'ORCID Podmínky služby veřejného klienta
• Klikněte na „Registrovat pro ORCID veřejné pověření API“.

Vyplnění formuláře Podrobnosti žádosti

• Jakmile se zaregistrujete pro své veřejné přihlašovací údaje API, budete přesměrováni zpět do nástrojů pro vývojáře (https://orcid.org/developer-tools or https://sandbox.orcid.org/developer-tools).
• Chcete-li zaregistrovat novou žádost, musíte vyplnit předložený formulář s podrobnostmi žádosti.
  • Jméno: Název vaší aplikace. Toto se zobrazí uživatelům, když udělí vaší aplikaci oprávnění k získání jejich ORCID iD a zobrazí se v jejich Seznam důvěryhodných organizací. Doporučujeme použít název vaší organizace nebo služby (např. Název deníku).
  • Adresa URL aplikace: Web, který může uživatel navštívit, aby se o vaší aplikaci dozvěděl více. To se také zobrazí v jejich Seznam důvěryhodných organizací.
  • Popis aplikace: Informace o aplikaci, kterou vyvíjíte, a o tom, jak ji budete používat ORCID iD. Toto se zobrazí uživatelům na obrazovce OAuth.

Přidání Přesměrování URI

Jakmile uživatel autorizuje vaši aplikaci, bude vrácen na URI, které určíte. Tyto identifikátory URI musíte zadat předem, jinak uživatelé integrace zaznamenají chybu.

• Do zobrazeného pole zadejte URI přesměrování
• Pokud potřebujete zadat více než 1 URI přesměrování, klikněte na „Přidat další URI přesměrování“

Upozornění:

• Pouze HTTPS URI jsou přijímány do výroby
• Registrované domény MUST přesně odpovídat použitým doménám, včetně subdomén
• Pokud je to možné, plně zaregistrujte všechny URI přesměrování. Toto je nejbezpečnější možnost a co doporučujeme. Další informace o URI přesměrování naleznete v našem FAQ přesměrování URI

Ukládání aplikace

Jakmile vyplníte formulář žádosti a přidáte své URI přesměrování, můžete svou žádost uložit.

• Klikněte na „Uložit moji aplikaci a vygenerovat moje ID klienta a tajný klíč“

Budete přesměrováni zpět na stránku vývojářských nástrojů, která nyní bude obsahovat vaše přihlašovací údaje klienta Public API

Aktualizace přihlašovacích údajů

Provedení změny informací v aplikaci je velmi jednoduché.

• Upravte příslušné informace a poté klikněte na „Uložit aplikaci“

Použijte své přihlašovací údaje

Nyní, když máte svá pověření, je čas začít používat ORCID Veřejné API!

Vezměte prosím na vědomí, že pokud se stanete členem, můžeme přenést vaše přihlašovací údaje do členského API ORCID člen v budoucnosti.

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

Kdokoli s veřejnými nebo členskými pověřeními API může obdržet / veřejné čtení přístupový token. Chcete-li získat token, zavolejte na ORCID Koncový bod tokenu API.

Tento proces se často označuje jako tok OAuth pověření klienta nebo dvoufázový OAuth.

Ukázkové volání k získání přístupového tokenu ke čtení veřejných dat na karanténě - nahraďte zástupné symboly vašimi pověřeními (nezapomeňte odstranit závorky.

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

Poté vám bude vrácen přístupový token podobný následujícímu. Vrácený token má dlouhou životnost (nevyprší po dobu přibližně 20 let) a lze jej použít několikrát k načtení veřejných dat z ORCID evidence. 

{"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}

Poznámka: Všechny tokeny s rozsahem / authenticate mají nyní také rozsah / read-public. Pokud používáte pouze obor / authenticate, můžete použít uložené přístupové tokeny ke čtení veřejných dat, aniž byste museli znovu získat přístupový token. 

Integrátoři používající členské API mohou používat / veřejné čtení prostor ke čtení ORCID souhrny záznamů.

Chcete-li získat přístup omezený na čtení, musíte požádat výzkumného pracovníka o povolení. Uděláte to pomocí OAuth. Konkrétně „3nohý OAuth".

Více informací naleznete na Výukový program API: Čtení dat na ORCID záznam

ORCID integrace používají „3 legged OAuth“ k autentizaci 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í veřejného rozhraní 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é „obory“, které specifikují konkrétní oblasti jejich záznamu, ke kterým chcete přistupovat. Po přihlášení uživatel autorizuje připojení k vašemu systému a je spolu s autorizačním kódem vrácen na vaši vstupní stránku. Tento kód se poté používá k získání jejich 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í sandbox server. 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 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.

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.

Tento příklad volání načte souhrn celého ORCID nahrávat ve formátu XML pomocí členské API na izolovaném serveru. K odeslání požadavků API na veřejné nebo členské API potřebujete přístupový token.

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

API vrátí zprávu 200 OK, což znamená, že požadavek byl úspěšně přijat, a úplné shrnutí ORCID záznam včetně přehledů jednotlivých položek.

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

Každá položka (práce, financování, zaměstnanost atd.) Má a vložte kód. To lze v případě potřeby použít k získání úplných podrobností o položce.

Jedno ORCID záznam je rozdělen do jednotlivých sekcí, aby bylo čtení záznamu rychlejší a konzistentnější. Nejprve můžete zavolat sekci, abyste získali její souhrn, a potom zavolat pomocí put kódu jednotlivých položek a získat podrobné informace o této položce.

Níže je uvedena tabulka souhrnných oddílů, které můžete ke čtení použít pomocí rozhraní API.

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.

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.

Jedno ORCID registr podporuje „vyjednávání obsahu“. To znamená, že stroje a další systémy se mohou zeptat ORCID registr pro metadata osob v různých formátech.

Jedním z těchto formátů je JSON-LD, který používá schema.org slovní zásoba, konkrétně typ osoby, které spojujeme s pracemi, organizacemi a dalšími identifikátory. Podporujeme také XML, JSON, RDF XML a želvu a implementovali jsme Cross-origin resource sharing (CORS), abychom usnadnili přístup k našim datům.

• Viz tento blogový příspěvek pro přehled ORCID a schema.org
• Podívejte se na naši technická dokumentace k vyjednávání obsahu

Hledání uživatele pomocí cURL takto:

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

Vrátí 200, i když uživatel není existovat. Chcete-li se tomu vyhnout, použijte ve svém hovoru vyjednávání obsahu takto:

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