Věci, které je třeba dokončit, než začnete
Než budete moci začít s tímto tutoriálem, musíte provést 3 níže uvedené kroky:
- Vyžádejte si přihlašovací údaje k rozhraní Sandbox Member API
- Vytvořte Sandbox ORCID účet
- Nakonfigurujte své hřiště Google Oauth
Pro tento tutoriál použijeme ORCIDtestovací prostředí ORCID pískoviště. Sandbox funguje stejně jako produkce ORCID Registr, až na několik výjimek:
- Sandbox odesílá e-maily pouze na mailinator.com Adresy
- Většina nástrojů průvodce importem v karanténě nefunguje
- Odkazy na nabídky na informační obsah (O aplikaci, Pro výzkumníky, Členství atd.) v izolovaném prostoru nefungují
- Sandbox neobsahuje žádná produkční data
Vyžádejte si přihlašovací údaje k rozhraní Sandbox Member API
Pověření API se skládají z a ID klienta a tajný shopper které jsou potřeba ke shromažďování ověřených ID a/nebo uživatelských oprávnění k interakci s jejich ORCID záznam. Požádejte o své přihlašovací údaje Sandbox zde. Přidejte poznámku s upozorněním, že testujete s Google OAuth Playground. Uvědomte si prosím, že se jedná o ruční proces a vytvoření přihlašovacích údajů může trvat až 24 hodin.
Vytvořte Sandbox ORCID účet
V novém okně nebo kartě navštivte https://sandbox.orcid.org/register
- Zadejte své jméno a e-mailovou adresu a poté klikněte na tlačítko „Další“. DŮLEŽITÉ! Nepoužívejte skutečnou e-mailovou adresu! Místo toho vytvořte adresu končící na @mailinator.com
- Dokončete krok 2 registračního formuláře heslem a přejděte ke kroku 3.
- Vyberte preferované nastavení viditelnosti, přijměte podmínky použití, klikněte na políčko vedle textu „Nejsem robot“ a nakonec klikněte na tlačítko „zaregistrovat se“.
Pamatujte si e-mail a heslo – budete je potřebovat v průběhu kurzu!
Nakonfigurujte svůj Google OAuth Playground
- Jít do Google OAuth Playground
- Klepnutím na ikonu ozubeného kola v pravém horním rohu otevřete Konfigurace OAuth 2.0
- Změňte rozevírací seznam Koncové body Oauth na Vlastní a zadejte následující nastavení a klikněte na Zavřít
Důležité! Nechte Google OAuth Playground otevřené, abyste nepřišli o konfigurace, které jste provedli ve výše uvedených krocích. Můžete také uložit adresu URL, která vám umožní inicializovat hřiště s těmito konfiguracemi (pro získání adresy URL klikněte na ikonu odkazu vedle ikony ozubeného kola v pravém horním rohu).
Shromažďování ověřeno ORCID ID a oprávnění
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í ke čtení a zápisu.
V této části si projdeme kroky, které by vaše vlastní integrace musela dokončit, abyste získali ověření iD a povolení číst a zapisovat do an ORCID záznam
Získání ověření iD a oprávnění k přístupu k záznamu od uživatele zahrnuje následující OAuth 2.0, standardní protokol pro autorizaci. OAuth umožňuje uživateli poskytnout webu nebo aplikaci přístup k informacím o účtu uloženým na jiném webu, aniž by tomuto webu sdělil své heslo.
Pokud jste se někdy přihlásili na web pomocí Googlu nebo Facebooku místo svých přihlašovacích údajů pro tento konkrétní web, již jste použili OAuth!
Proces OAuth zahrnuje 3 kroky:
- Vytvořte autorizační adresu URL
- Získejte autorizační kód
- Vyměňte autorizační kód za přístupový token
Abychom mohli zahájit proces OAuth, budeme muset vytvořit speciální autorizační adresu URL, která uživatele pošle na adresu ORCID přihlašovací obrazovka. Tato adresa URL se skládá z Koncový bod autorizace, Plus parametry které identifikují vaši organizaci a oprávnění, o která chcete požádat.
Chcete-li požádat o povolení k přidání/aktualizaci aktivit (afiliace, financování, díla, vzájemné hodnocení, výzkumné zdroje) a k přidání/aktualizaci osobních položek (jiná jména, klíčová slova, země, adresy URL výzkumníků, webové stránky a osobní externí identifikátory), autorizační URL bude:
https://sandbox.orcid.org/oauth/authorize?client_id=[APP-****************]&response_type=code&scope=/read-limited%20/activities/update%20/person/update&redirect_uri=https://developers.google.com/oauthplaygroundMůžeme však použít hřiště Google OAuth, které nám pomůže vytvořit autorizační adresu URL
Do pole Rozsahy přidejte /activities/update, /person/update, /read-limited a klikněte na autorizovat API.
Autorizační adresa URL by byla vytvořena pomocí informací, které jste zadali do polí konfigurace a rozsahu.
An ORCID objeví se přihlašovací obrazovka; přihlaste se ke svému účtu Sandbox pomocí e-mailové adresy a hesla, které jste použili k vytvoření účtu ORCID účet na začátku tohoto tutoriálu. Jakmile se přihlásíte, zobrazí se obrazovka OAuth. Na této obrazovce se zobrazí jméno klienta a příslušné rozsahy, které byly zahrnuty do autorizační adresy URL. Pro udělení přístupu musíte kliknout na 'Autorizovat přístup'
Po udělení povolení budete přesměrováni zpět na Google OAuth Playground, protože se jednalo o URI přesměrování spojené s vašimi přihlašovacími údaji Sandbox. Šestimístný autorizační kód se objeví na konci URI přesměrování v adresním řádku prohlížeče (a pod Krok 2 sekce na levé straně stránky na hřišti Google Oauth)
Jakmile budete mít autorizační kód, můžete jej vyměnit za přístupový token a Authenticated iD uživatele, který se přihlásil, což budete potřebovat k provedení akcí API, pro které jste požadovali oprávnění.
Pokud ztratíte přístupový token, můžete proces dokončit znovu, ale nejprve budete muset zrušit oprávnění pro klientskou aplikaci, pokud používáte stejnou ORCID iD. Oprávnění lze zrušit odebráním klientské aplikace ze sekce „Důvěryhodné organizace“ na stránce „Důvěryhodné strany“
V reálné situaci by tuto výměnu provedl váš systém pomocí programovacího jazyka, jako je PHP, Java nebo Ruby on Rails. V tomto tutoriálu použijeme Google OAuth Playground k simulaci webové aplikace.
klikněte „Vyměnit autorizační kód za tokeny“
Jakmile kliknete na „Vyměňte autorizační kód za tokeny” Váš přístupový token a ověřeno iD se objeví v Vyžádat odpověď sekce vpravo. Podívejte se prosím na níže uvedený příklad:
Uložte si tento token!
Token, který jste obdrželi ve výše uvedeném kroku, je důležité uložit, protože s ním můžete snadno provádět hovory, které potřebujete. Doporučujeme, abyste si uložili úplnou odpověď výměny tokenů
Nyní jste shromáždili ověřený ID a povolení od uživatele číst jejich ORCID zaznamenávat a aktualizovat jejich ORCID záznam.
Psaní do an ORCID záznam (POST)
V této sekci přidáme do vašeho záznamu v Sandboxu příslušnost ke vzdělání. V následujícím příkladu používáme koncový bod /education s správné XML přidat informace, ale stejně tak můžete přidat například Zaměstnání nebo Práce. Podívejte se na naše Dokumentace Github další příklady souborů a koncových bodů a oprávnění, která pro každý z nich potřebujete.
Zde je příklad XML pro vzdělávání, který můžete použít pro toto cvičení:
<?xml version="1.0" encoding="UTF-8"?>
<education:education
xmlns:common="http://www.orcid.org/ns/common" xmlns:education="http://www.orcid.org/ns/education"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.orcid.org/ns/education ../education-3.0.xsd ">
<common:department-name>department-name</common:department-name>
<common:role-title>role-title</common:role-title>
<common:start-date>
<common:year>1948</common:year>
<common:month>02</common:month>
<common:day>02</common:day>
</common:start-date>
<common:end-date>
<common:year>1948</common:year>
<common:month>02</common:month>
<common:day>02</common:day>
</common:end-date>
<common:organization>
<common:name>common:name</common:name>
<common:address>
<common:city>common:city</common:city>
<common:region>common:region</common:region>
<common:country>AF</common:country>
</common:address>
<common:disambiguated-organization>
<common:disambiguated-organization-identifier>http://dx.doi.org/10.13039/100000001</common:disambiguated-organization-identifier>
<common:disambiguation-source>FUNDREF</common:disambiguation-source>
</common:disambiguated-organization>
</common:organization>
<common:url>http://tempuri.org</common:url>
<common:external-ids>
<common:external-id>
<common:external-id-type>grant_number</common:external-id-type>
<common:external-id-value>external-identifier-value</common:external-id-value>
<common:external-id-url>http://tempuri.org</common:external-id-url>
<common:external-id-relationship>self</common:external-id-relationship>
</common:external-id>
<common:external-id>
<common:external-id-type>grant_number</common:external-id-type>
<common:external-id-value>external-identifier-value2</common:external-id-value>
<common:external-id-url>http://tempuri.org/2</common:external-id-url>
<common:external-id-relationship>self</common:external-id-relationship>
</common:external-id>
</common:external-ids>
</education:education>Vraťte se na kartu prohlížeče Google Playground. Pokud jste kartu nenechali otevřenou, můžete relaci znovu inicializovat pomocí adresy URL, kterou jste dříve uložili (kliknutím na tlačítko OK na varování, které se objeví). Nebo můžete hovor znovu nastavit vyplněním všech příslušných polí a ujistěte se, že vypadají jako na snímcích níže:
- Ujistěte se, že konfigurace má váš zákazník ID a tajemství klienta
- níže v kroku 2 na hřišti Google Oauth byste měli mít svůj přístupový token vyplněny
Buď by měl mít stále token z dřívějška, nebo ho můžete vyplnit z předchozího cvičení takto: - Pod krokem 3 Klikněte Přidejte záhlaví, zadejte níže uvedené hodnoty a klikněte přidat a zavřít
- Název záhlaví: akceptovat
- Hodnota záhlaví: aplikace/vnd.orcid+xml
- Pod krokem 3: Nakonfigurujte požadavek na API, nastavte metodu HTTP na POST.
- v URI požadavku pole zadejte:
https://api.sandbox.orcid.org/v3.0/[ORCID ID]/education
Nahradit [ORCID ID] s iD pro váš záznam v Sandboxu naformátujte XXXX-XXXX-XXXX-XXXX, se kterým jste získali oprávnění k interakci. - klikněte Typ obsahu > Zvyk a zadejte application/vnd.orcid+xml Klikněte přidat, poté klepněte na tlačítko zavřít.
- klikněte Zadejte tělo požadavku.
Zkopírujte XML příslušnost ke vzdělání v horní části této sekce a vložte jej do Tělo žádosti Textové pole
VOLITELNÝ: v Tělo žádosti textovém poli upravte XML tak, aby odrážel vaši instituci.
Pro , použijte Registr ROR najít ROR ID pro vaši institucin.
klikněte zavřít.
- klikněte Odeslat žádost.
Výsledky se objeví v Vyžádat odpověď sekce vpravo. Přejděte dolů – pokud vidíte HTTP/1.1 201 Vytvořeno, vaše vzdělání bylo úspěšně přidáno!
Uložte také svůj put kód, který bude vyžadován v další sekci!
Navštivte veřejné zobrazení vašeho záznamu Sandbox na https://sandbox.orcid.org/[ORCID ID], abyste viděli svou novou příslušnost ke vzdělání.
Všimněte si, že Zdroj zobrazuje název klienta API, který přidal příslušnost – to je klíčový prvek, který pomáhá jiným systémům spotřebovávat ORCID data určují, zda je tato informace směrodatná.
Aktualizace ORCID záznam (PUT)
V reálné situaci možná budete muset aktualizovat příslušnost výzkumníka. V této sekci aktualizujeme naši příslušnost ke vzdělávání tak, aby zahrnovala datum ukončení.
Put kódy jsou krátké číselné kódy, které odkazují na konkrétní položku na ORCID záznam. Kód put použijete s voláním API k aktualizaci, odstranění nebo čtení konkrétní položky (na rozdíl od souhrnu položek.)
Každá položka v ORCID iD je přiřazen put kód, který jej jednoznačně identifikuje. Při čtení celého záznamu nebo sekce lze put kód najít jako atribut položky. Když volání konkrétní položky v záznamu, put kód se používá k identifikaci položky. Put kódy jsou jedinečné v rámci typu položky, na kterou odkazují. Pomocí tohoto příkladu pracuje pouze jedna v ORCID Registr bude mít put kód 733535, ačkoli 733535 může být také použit jako put kód pro položku financování nebo klíčové slovo.
Když odešlete položku do záznamu výzkumníka, odpověď API bude obsahovat kód pro tuto položku. Vložte kód můžete uložit a použít jej později, pokud budete potřebovat danou položku přečíst, aktualizovat nebo odstranit.
Abychom zjistili put kód pro konkrétní položku, kterou nemáme, stačí si přečíst záznam nebo souhrn sekce, kde se tato položka nachází. Put kód pro položku, kterou chceme upravit, bude vrácen v odpovědi.
V níže uvedeném příkladu aktualizujeme jednu položku vzdělávání.
Poznámka: Pokud jste si uložili kód put pro vaši příslušnost ke vzdělání, můžete přeskočit na krok 4 níže. Pokud jste kód vložení neuložili, začněte prosím krokem 1 níže.
- Nejprve musíme získat a vložte kód pro vzdělávací příslušnost, kterou jste právě přidali, otevřete nové okno Google Playground a nastavte jej podle prvních 4 kroků ze sekce Začínáme
- Tentokrát do pole URI požadavku zadejte https://api.sandbox.orcid.org/v3.0/0000-XXXX-XXXX-XXXX/vzdělávání . Všimněte si, že jsme přidali /educations na konec URI a že je množné. To znamená, že načítáme souhrn všech položek vzdělání v tomto záznamu, ne pouze jednu (uvedli bychom to singulární a na konec přidali /put-code položky)
- Klikněte na 'Odeslat žádost' a měli byste vidět něco jako obrázek níže v Vyžádat odpověď sekce. Najít vložte kód pro příslušnost ke vzdělání, kterou jste přidali v předchozí části (bude to jiné číslo než zde zvýrazněné).
- Přeměna Metoda HTTP na PUT
- klikněte Přidat záhlaví a ujistěte se, že Accept a Content-type jsou obě nastaveny na application/vnd.orcid+xml
- v URI požadavku pole zadejte:
https://api.sandbox.orcid.org/v3.0/[ORCID ID]/education/[PUT CODE]
Nahradit [ORCID ID] s iD pro záznam v karanténě naformátujte XXXX-XXXX-XXXX-XXXX a [PUT CODE] s vloženým kódem pro vaši příslušnost ke vzdělání - Znovu uchopte XML ze sekce POST a klikněte Zadejte tělo požadavku a vložte jej.
- Upravte datum ukončení vaší příslušnosti ke vzdělání
- klikněte zavřít.
- Klikněte na Odeslat požadavek.
- Výsledky se objeví v Vyžádat odpověď sekce vpravo. Přejděte dolů – pokud vidíte HTTP / 1.1 200 OK, vaše příslušnost ke vzdělání byla úspěšně aktualizována! Pokud se zobrazí chybová zpráva, zkontrolujte, zda jsou hodnoty záhlaví v Přidejte záhlaví nebyly změněny na zkomolený text, např. application%2Fvnd.orcid%2Bxml”
- Navštivte pohled veřejnosti vašeho záznamu Sandbox na https://sandbox.orcid.org/[ORCID ID], abyste viděli svou aktualizovanou příslušnost ke vzdělání s novým datem ukončení.
Čtení a ORCID Záznam (GET)
Vraťte se na kartu prohlížeče Google Playground. Pokud jste kartu nenechali otevřenou, můžete relaci znovu inicializovat pomocí adresy URL, kterou jste dříve uložili (kliknutím na tlačítko OK na varování, které se objeví). Nebo můžete hovor znovu nastavit vyplněním všech příslušných polí a ujistěte se, že vypadají jako na snímcích níže:
- Ujistěte se, že konfigurace má váš zákazník ID a tajemství klienta
- Krok 2 byste měli mít svůj přístupový token vyplněny
Buď by měl mít stále token z dřívějška, nebo ho můžete vyplnit z předchozího cvičení takto: - Krok 3 Klikněte na Přidejte záhlaví, zadejte níže uvedené hodnoty a klikněte přidat a zavřít
- Název záhlaví: akceptovat
- Hodnota záhlaví: aplikace/vnd.orcid+xml
- Krok 3 Konfigurace by měl vypadat jako na obrázku níže:
- Nastavte metodu HTTP na GET.
- Do pole URI požadavku zadejte:
https://api.sandbox.orcid.org/v3.0/0000-XXXX-XXXX-XXXX/record
Nahradit [ORCID ID] s iD pro váš záznam Sandbox naformátujte XXXX-XXXX-XXXX-XXXX
Poznámka: Koncový bod je slovo na konci URI. V tomto případě čteme a shrnutí celého záznamu, takže URL ukončíme /record, jak je uvedeno výše. - klikněte Odeslat žádost
V poli Požadavek/Odpověď byste měli vidět souhrn XML celého záznamu. Bude to vypadat trochu jako příklad níže, který ukazuje první část odpovědi. Zvýraznili jsme put kódy, jak je uvedeno v předchozí části
