APIチュートリアル：レコードのデータを読み取る

開発者は、パブリックAPIをテストすることをお勧めします。 サンドボックス テスト サーバー 製品版を使用する前に。以下は、サンドボックス環境と運用環境の両方でパブリック API 認証情報を登録する方法の手順です。

• あなたにサインインします ORCID 記録：
  本番サーバー： https://orcid.org/signin
  サンドボックステストサーバー： https://sandbox.orcid.org/signin
• 右上隅にあるあなたの名前をクリックしてください
• クリック 開発者ツール メニューオプションから
  ご注意： 開発者ツールにアクセスするには、電子メール アドレスを確認する必要があります。 電子メール アドレスをまだ検証していない場合は、パブリック API 認証情報を登録する前に検証するように求められます。
• を読み、同意します。ORCID パブリッククライアントの利用規約
• 「登録」をクリックします ORCID パブリック API 認証情報」ボタンをクリックします。

申請詳細フォームに記入する

• パブリック API 資格情報を登録すると、開発者ツールに戻ります (https://orcid.org/developer-tools or https://sandbox.orcid.org/developer-tools).
• 新しいアプリケーションを登録するには、表示されるアプリケーション詳細フォームに記入する必要があります。
  • 名前：アプリケーションの名前。 これは、ユーザーがアプリケーションにユーザーを取得する権限を付与したときに表示されます ORCID iD、そしてそれは彼らに表示されます 信頼できる組織リスト。 組織またはサービスの名前（ジャーナル名など）を使用することをお勧めします。
  • アプリケーションURL: ユーザーがアプリケーションの詳細を知るためにアクセスできる Web サイト。 これは彼らの記事にも表示されます 信頼できる組織リスト.
  • アプリケーションの説明：開発中のアプリケーションとユーザーの使用方法に関する情報 ORCID iD。 これは、OAuth画面でユーザーに表示されます。

追加 URIをリダイレクトする

ユーザーがアプリケーションを承認すると、指定したURIに返されます。 これらのURIを事前に提供する必要があります。そうしないと、統合ユーザーでエラーが発生します。

• 表示されたボックスにリダイレクト URI を入力します
• 複数のリダイレクト URI を入力する必要がある場合は、「別のリダイレクト URI を追加」をクリックします。

※

• のみ HTTPS URI 本番環境で受け入れられます
• 登録されたドメイン MUST サブドメインを含め、使用されているドメインと完全に一致する
• 可能な場合は、すべてのリダイレクト URI を完全に登録します。 これは最も安全なオプションであり、推奨されます。 リダイレクト URI の詳細については、「 リダイレクト URI に関するよくある質問

アプリケーションを保存する

アプリケーション フォームに記入し、リダイレクト URI を追加したら、アプリケーションを保存できます。

• 「アプリケーションを保存してクライアントを生成」をクリックします ID そして秘密」

開発者ツールのページに戻ります。このページには、パブリック API クライアントの認証情報が含まれています。

資格情報を更新する

アプリケーション情報の変更は非常に簡単です。

• 関連情報を編集し、「アプリケーションを保存」をクリックします。

クレデンシャルを使用する

クレデンシャルを取得したので、次は ORCID パブリックAPI！

あなたが ORCID メンバー 将来インチ

また、ご購読はいつでも停止することが可能です サンドボックスメンバーAPIクレデンシャルをリクエストする アプリケーションを構築してテストします。これらの資格情報により、サンドボックスプレミアムメンバーAPIを呼び出して読み取り、書き込み、更新を行うことができます。 ORCID 記録。 サンドボックステスト環境へのアクセスは、あなたがそうでなくても、誰でも自由に利用できます。 ORCID メンバー組織。

Note: を使用している場合 ORCID すでにサポートしている認定サービスプロバイダーシステム ORCIDサンドボックスAPIの認証情報を登録する必要はありません。 ORCID サンドボックス環境内での統合機能。 

サンドボックスを使用すると、ライブ（本番）のデータに影響を与えることを心配することなく、テストユーザーアカウントを作成して統合を開発できます。 ORCID レジストリ。 サンドボックスは本番環境と同じように動作します ORCID とのレジストリ いくつかの例外.

テストアカウントの作成

テストするために ORCID への情報の読み取りや追加などの API および API 呼び出し ORCID 記録するには、テストも作成する必要があります ORCID サンドボックスに記録します。 これは、本番環境と同様に、ユーザーインターフェイスを介して実行できます。 ORCID レジストリ。 に移動 https://sandbox.orcid.org/register アカウントに登録します。

Mailinatorのメールアドレス

サンドボックスサーバーは、 Mailinator （@ mailinator.com）意図せずにメールサーバーにスパムを送信しないための電子メールアドレス。 @ mailinator.comアドレスを使用しない限り、確認メールまたはパスワードリセット通知を受信しません。サンドボックスレコードを手動で編集するには、確認が必要です。 自由に使用できる公開受信トレイの詳細をご覧ください ページ をご覧ください 使用したくない場合 Mailinator ユーザー名とパスワードを書き留めて (テスト時にアプリケーションに承認を与えるために使用するため)、検証の支援を依頼するために当社に連絡してください。

Mailinator は、パブリック無料サービスとプライベート有料サービスを備えたメール サービスです。 テストには、完全に無料のパブリック サービスを使用できます。 ティアの詳細を確認する （茶事の話はこちらをチェック）.

Mailinatorは、によって管理または保守されていないサードパーティのサービスです ORCID。 これらのアドレスを使用する前に、このサービスの動作と制限を確認することをお勧めします。

パブリックまたはメンバーAPIクレデンシャルを持っている人は誰でも受け取ることができます / read-public アクセストークン。 トークンを取得するには、に電話をかけます ORCID APIトークンエンドポイント。

このプロセスは、クライアントクレデンシャルOAuthフローまたは2ステップOAuthと呼ばれることがよくあります。

サンドボックス上の公開データを読み取るためのアクセストークンを取得するための呼び出しの例—プレースホルダーを資格情報に置き換えます（必ず角かっこを削除してください）。

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

次に、次のようなアクセス トークンが返されます。 返されたトークンの有効期間は長く (約 20 年間は期限切れになりません)、パブリック データを取得するために複数回使用できます。 ORCID レコード。 

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

ご注意： / authenticateスコープを持つすべてのトークンには、/ read-publicスコープも含まれるようになりました。 / authenticateスコープのみを使用する場合は、保存されているアクセストークンを使用して、アクセストークンを再度取得しなくてもパブリックデータを読み取ることができます。 

メンバー API を使用するインテグレーターは、 / read-public 読む範囲 ORCID 記録の概要。

/読み取り制限付きアクセスを取得するには、研究者に許可を求める必要があります。 これは OAuth を使用して行います。 具体的には、 "3本足のOAuth"

詳細については、 APIチュートリアル：データを読み取る ORCID 記録

ORCID 統合では、「3レッグOAuth」を使用してユーザーを認証し、ユーザーのレコードを操作するための許可を要求します。 どの統合でも、パブリックAPIを使用して読み取り権限を要求できます。 ORCID メンバーは Member API を使用して更新権限を要求できます。それはこのように動作します：

• 特別なリンクを作成します
• クリックすると、ユーザーはに送信されます ORCID
  • ORCID ユーザーにサインインするように求めます
  • ORCID アプリケーションに権限を付与するようにユーザーに要求します
  • ORCID 認証コードを使用してユーザーをシステムに送り返します
• システムはそのコードをアクセストークンと交換します

カスタマイズされた認証 URL には、クライアント情報に加えて、アクセスしたいレコードの特定の領域を指定する「スコープ」が含まれます。サインイン後、ユーザーはシステムとの接続を認証し、認証コードとともにランディング ページに返されます。このコードは、そのコードを取得するために使用されます。 ORCID iD 要求されたスコープに有効なアクセストークンとともに。

認証リンクを作成し、認証コードを取得してください

APIクレデンシャルのクライアントを指定して認証リンクを構築します ID および関連するランディング ページ (リダイレクト URI)。設定によってどの権限を要求するかを選択します スコープパラメータ.

以下の例では、アクセスが制限されたデータを読み取る許可を要求しています。 ORCID サンドボックステストサーバー。実際の世界では、このリンクを Web サイトに表示するか、ユーザーに認証と承認を求めるときに電子メールに含めます。ただし、テスト目的であれば、Web ブラウザに貼り付けるだけで済みます。角括弧で囲まれたデータをクライアント情報に置き換えてください。角括弧は必ず削除してください。

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

ユーザーがリンクをクリックし、でサインインした場合 ORCID 付与されたアクセス許可は、次のようにサイトにリダイレクトされます。

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

認証コードを ORCID iD およびアクセストークン

すぐに認証コードを交換する必要があります ORCID iD そしてアクセストークン。認証コードは使用すると期限切れになります。リクエストは次のようになります。 Webブラウザでは作成できません、サーバーで作成する必要があります。

 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 その後、研究者の認証済みを返します ORCID iD および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"}

アクセストークンはデフォルトで長期間有効であり、発行後20年で有効期限が切れます。 トークンは、有効期限が切れる前に複数回使用できます。

アクセストークンを使用する

3本足のアクセストークンは特定のものにリンクされています ORCID 記録。これらを使用するには、そのレコードを読み取りまたは更新するために行う API リクエストにそれらを含めます。

可視性は、ユーザーが設定した可視性設定に基づいて、アイテムのプライバシー設定を示します。 APIを介して情報が投稿されるときに可視性タグが含まれている場合、それは無視されます。 むしろ、情報は、アカウント設定で設定されたユーザーのデフォルトの表示設定に従って投稿されます。

公開アイテムは、API を介して誰でも読み取ることができ、研究者の公開記録に表示されます。信頼できるパーティ アイテムは、API を介して、読み取りが制限されたアクセスを持つクライアントにのみ返されます。それらは研究者の公的記録には載っていない。プライベート アイテムは、研究者とアイテムのソースにのみ表示されます。API 経由で返されるプライベート アイテムのみが、統合を通じてレコードに追加されたものです。 の可視性設定の詳細 ORCID レジストリ.

この例の呼び出しは、完全な要約を取得します ORCID サンドボックスサーバーのメンバーAPIを使用してXML形式で記録します。 パブリックAPIまたはメンバーAPIにAPIリクエストを行うには、アクセストークンが必要です。

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は、リクエストが正常に受信されたことを示す200 OKメッセージと、 ORCID 個々の項目の要約を含む記録。

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

各項目（仕事、資金、雇用など）には コードを入れる。 必要に応じて、これを使用してアイテムの完全な詳細を取得できます。

この ORCID レコードは個々のセクションに分割され、レコードの読み取りをより速く、より一貫性のあるものにします。 最初にセクションを呼び出してその概要を受け取り、次に個々のアイテムのプットコードを使用して呼び出して、そのアイテムに関する堅牢な情報を受け取ることができます。

APIを使用して読み取ることができる要約セクションの表を以下に示します。

上のすべてのアイテム（伝記のテキストを除く） ORCID レコードには コードを入れる:

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

このプットコードを使用してAPIを呼び出し、アイテムの完全なデータを取得できます。 以下の項目は、 コードを入れる:

セクションエンドポイントとプットコードを使用すると、同じアクセストークンを使用してAPIを呼び出して、特定のアイテムを完全に取得できます。 この例の呼び出しは、サンドボックスサーバー上のメンバーAPIを使用して、XML形式で完全な資金調達アイテム4413を取得します。

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

呼び出し例：GitHub

APIは、メッセージが正常に受信されたことを示す200 OKメッセージを返し、資金調達アイテムの完全なXMLを返します。

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

あなたがチェックすることができます アイテムのソース 誰が追加したのか知りたい場合は、読んでください。

で働く ORCID それらの識別子とそれらの識別子、作品との関係の両方に基づいてグループ化されます。 関係には次の XNUMX 種類があります。

• 自己：識別子はその作品のみを参照し、同じ識別子を持つ他の作品とグループ化できます
• の一部：作品はこの識別子の一部であり、他の作品とグループ化することはできません
• のバージョン：これらの識別子は作品の代替バージョンに適用され、自己およびバージョンの識別子とグループ化できます
• によって資金を供給：これらの識別子は、作業の資金に適用されます。 これらの識別子は、作業のグループ化には使用されません。

当社の API は、XSD でこれをサポートしています。各アイテムには、グループ内でのランクを示す表示インデックス属性があります。最も高い表示インデックスは、研究者が選択した優先アイテムです。API 経由で追加されたアイテムで、研究者によってランク付けされていないアイテムには表示インデックス 1 が付けられ、研究者によって変更されるまで、グループ内のデフォルトの優先ソースとして使用されます。表示インデックスは、アイテムを読み込むときの作業順序も決定します。 ORCID API を使用して記録します。

のグループ化に関する詳細については ORCID 記録、私たちを参照してください サポート記事.

この ORCID レジストリは「コンテンツ ネゴシエーション」をサポートします。 これは、マシンや他のシステムが質問できることを意味します。 ORCID さまざまな形式の個人メタデータのレジストリ。

これらの形式のXNUMXつはJSON-LDであり、これは schema.org 語彙、具体的には 個人タイプ、私たちは作品、組織、その他の識別子と結びつけます。 また、XML、JSON、RDF XML、タートルもサポートしており、データに簡単にアクセスできるようにクロスオリジン リソース共有 (CORS) を実装しています。

• こちらを参照してください。 の概要についてのブログ投稿 ORCID およびschema.org
• 取り付けガイドを参照してください。 コンテンツ ネゴシエーションに関する技術文書

次のようにcURLを使用してユーザーを検索します。

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

ユーザーが200を返します しない 存在。 これを回避するには、次のように通話でコンテンツネゴシエーションを使用します。

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