このチュートリアルでは、に情報を追加する方法について説明します。 ORCID 記録、データのフォーマット ORCID メッセージスキーマ、および以前に追加したデータの更新または削除 ORCID 記録。
クライアントの資格情報を取得する
クライアントのクレデンシャルは、アプリケーション/ウェブサイトがアクセスするために使用するユーザー名とパスワードです。 ORCID API。 誰でも読み取り専用のパブリックAPIクレデンシャルに登録できます。 ORCID メンバーはメンバーAPIに登録できます。
のメンバーAPIクレデンシャルが必要になります サンドボックス テスト サーバー、およびのテスト記録 ORCID アイテムの追加と更新をテストするためのサンドボックス ORCID 記録。
また、ご購読はいつでも停止することが可能です サンドボックスメンバーAPIクレデンシャルをリクエストする アプリケーションを構築してテストします。これらの資格情報により、サンドボックスプレミアムメンバーAPIを呼び出して読み取り、書き込み、更新を行うことができます。 ORCID 記録。 サンドボックステスト環境へのアクセスは、あなたがそうでなくても、誰でも自由に利用できます。 ORCID メンバー組織。
注意: を使用している場合 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。 これらのアドレスを使用する前に、このサービスの動作と制限を確認することをお勧めします。
レコードを更新する許可を取得する
に関する情報を追加または更新するには ORCID レコードの場合、最初にレコード所有者の許可を取得する必要があります。 それだけ ORCID メンバーは更新権限を要求できます。これは、「/ activity / update」および/または「/ person / update」スコープはOAuthを使用します。
XNUMXつの異なる更新スコープがあります。XNUMXつは経歴の詳細用で、もうXNUMXつはアクティビティ用です。
対象領域 | 説明 | APIエンドポイント |
/ person / update | 経歴データ - の左の列 ORCID ユーザーインターフェイスを記録します。 | /住所 / external-識別子 / keywords /他の名前 / researcher-urls |
/ activity / update | 研究活動データー右欄 ORCID ユーザーインターフェイスを記録します。 | /区別 / distinctions /教育 /教育 /雇用 /雇用 /資金 / fundings / invited-position / invited-positions / membership / memberships /ピアレビュー /ピアレビュー /資格 /資格 / research-resource / research-resources /サービス / services /作業 / works |
ORCID 統合では、「3レッグOAuth」を使用してユーザーを認証し、ユーザーのレコードを操作するためのアクセス許可を要求します。 どの統合でも、パブリックAPIを使用して読み取り権限を要求できます。 ORCID メンバーは、メンバー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 とアクセストークン。 認証コードは使用時に期限切れになります。 リクエストは次のようになり、 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リクエストにそれらを含めます。
と対話する許可を要求するとき ORCID ユーザーのレコードでは、XNUMX つ以上の「スコープ」を指定します。 各スコープでは、レコードの読み取りや特定のセクションの更新など、特定の操作を行うことができます。
3脚 ユーザーからの許可の取得に関与するXNUMX人のアクターを指します。 ORCID、システムとユーザー自身。
/認証する 
このスコープは、 ORCID iD 記録上の公開情報のみを読んでください。 他のすべての3脚スコープには認証権限が含まれているため、他のアクセスを要求する場合は、このスコープを省略できます。 このスコープは、メンバーAPIまたはパブリックAPIで使用できます。
/ read-limited(メンバーAPIのみ) 
このスコープは、公開されている可視性のアイテムを読み取るためのアクセス権を取得するために使用されます。 ORCID 記録。 このスコープは、メンバーAPIでのみ使用できます。
/ Activities / update(メンバーAPIのみ) 
このスコープは、所属、資金、作品、専門活動、研究リソース、査読セクションの項目を書き込み、更新、削除するために使用されます。 ORCID 記録。 このスコープは、メンバーAPIでのみ使用できます。
/ person / update(メンバーAPIのみ) 
このスコープは、レコードの他の名前、キーワード、国、研究者のURL、Webサイト、および個人の外部識別子セクションの項目を書き込み、更新、および削除するために使用されます。 このスコープは、メンバーAPIでのみ使用できます。
オープンID
このスコープは、id_tokenが必要な場合にOpenIDインテグレーターによって使用されます。 openidスコープが含まれている場合、レジストリはトークン応答内にid_tokenを返し、そのユーザーのユーザー情報エンドポイントにアクセスするためのアクセス許可をクライアントに付与します。 このスコープは、パブリックAPIとメンバーAPIで利用できます。
'openid'スコープは他のように '/'で始まらないことに注意してください ORCID APIスコープ。 これは、「openid」スコープがによって定義されていないためです。 ORCID、ただし、代わりにOpenIDConnect仕様で定義されています。 ご覧ください OpenIDドキュメント をご覧ください。
複数のスコープ
scope = / read-limited%20 / Activities / update%20 / person / updateのように、認証URLのスコープをそれぞれの間にエンコードされたスペースでリストすることにより、XNUMX回の対話で複数のスコープを要求できます。
完全なアクセス
レコードを読み取って編集するためのフルアクセスが必要な場合は、認証URLに/ read-limited、/ activitys / update、および/ person / updateの20つのスコープを含めます。 URLでは、scope = / read-limited%20 / Activities / update%XNUMX / person / updateとして表示されます。
2本足(クライアントクレデンシャル)スコープ
一部のアクティビティでは、ユーザーに許可を求める必要はありません。 XNUMX つのレッグ OAuth スコープが、 ORCID APIであり、研究者が許可を与える必要はありません。 これらのスコープを持つトークンは20年間有効であり、再利用できます
/ read-public
このスコープは、単一の公開情報を読み取るために使用されます ORCID iD、検索 ORCID レコードを表示したり、概要情報を読み取ったりできます (メンバー API のみ)。このスコープは、メンバー API またはパブリック API で使用できます。
/ webhook
このスコープにより、クライアントアプリケーションはWebhookを ORCID レコード、レコードが更新されたときに通知を受信するため。 このスコープはプレミアムで利用可能です ORCID メンバーのみ。
アイテムの追加
アイテム(仕事、雇用、資金調達、ピアレビューなど)をに追加することができます ORCID を使用して記録する ORCID メンバーAPI。 それらは、アイテムの「ソース」としてクライアント名とともに表示されます。
アイテム(仕事、雇用、資金調達、ピアレビューなど)をに追加することができます ORCID を使用して記録する ORCID メンバーAPI。 これを行うには、まず次のことを行う必要があります OAuthを使用して研究者から許可を得る と アイテムのメタデータをフォーマットする ORCID メッセージスキーマ。
データをフォーマットして収集したら、 ORCID iD トークンにアクセスするには、HTTP POSTを使用してAPIリクエストを行い、 関連するエンドポイント.
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
以下の呼び出しは、新しいを追加します 雇用 サンドボックステストサーバー上のレコードへの所属:
<?xml version="1.0" encoding="UTF-8"?>
<employment:employment [...]>
[...]
</employment:employment>
API は 201 メッセージを返し、アイテムが正しく投稿されたことを示します。 コードを入れる。 あなたのクライアントは次のようにリストされます。 アイテムのソース.
私たちをチェック トラブルシューティング 別のメッセージが返された場合はページ。 保存する必要があります プットコードとアクセストークンを保存する 更新を行うか、アイテムを削除します。
An ORCID 記録には、研究者の仕事、所属、資金提供、査読などに関する情報が含まれる場合があります。
上のアイテム ORCID レコードは次のように分類できます アサーション 接続する ORCID 活動または所属のiD保有者. これらのアサーションは、 ORCID 記録を所有する研究者による記録、または研究者がそうすることを許可したシステムによる記録。 アサーションを追加したエンティティを ORCID 記録する source.
例


透明性と開放性の原則に従い、アサーションのソース、つまり誰がその情報をレコードに追加しているかを確認できることが重要であると考えています。 これが私たちのやり方です:
- 研究者(または彼らの委任された 信頼できる個人)レコードにアサーションを追加し、 ORCID その人をソースとして自動的に記録します
- 研究者によって承認されたシステムがレコードにアサーションを追加すると、 ORCID システム所有者を自動的に記録します( ORCID メンバー) をソースとして使用します。
ソース名をユーザーインターフェイスに表示し、APIで(一意の識別子を使用して)使用できるようにします。
ただし、調査情報のワークフローはこれよりも複雑になる可能性があり、アサーションの実際のソースは、あるシステムが人または別のシステムに代わってアイテムを追加することによって意図せずに隠される可能性があります。 透明性を確保するために、誰が人とアイテムを結び付けたのか、誰がアイテムをレコードに追加したのかを区別する必要があります。 上記のように、アイテムをに追加する人は誰でも ORCID レコードは source; 間の接続を作成する人 ORCID iD そしてアイテムは アサーションの起源。
例:
- 研究者はデータを自分の ORCID 検索およびリンクウィザードなどのシステムからの記録。 研究者は彼らをつなぐ主張をしている iD アイテムと一緒に、彼らは アサーションの起源; システムがアサーションをに追加するエンティティである間 ORCID 記録— source
- 研究者はシステムAと対話します( アサーションオリジ)、システムBが提供するサービスを使用して更新します ORCID 記録、システムBを source

私たちは、コミュニティがアサーションの起源に関する情報を保存および共有するための措置を講じることを奨励します。これにより、誰もがソースを見ることで利益を得ることができます。
詳細については、以下を参照してください。
アイテムの更新
追加した情報を保持することをお勧めします ORCID 最新の記録。 たとえば、従業員が退職するときに雇用に終了日を追加したり、公開された記事の識別子をデータセットに追加したりします。
ORCID メンバーは、以前に追加した情報を更新できます。 ORCID 記録。 一度に更新できるアイテムはXNUMXつだけであり、最初にアイテムを作成したクライアントのクレデンシャルを使用してのみ更新できます。
更新を容易にするために、 プットコードとアクセストークンを保存する アイテムを作成するとき。
更新されたアイテムをフォーマットします in ORCID メッセージスキーマ 変更された情報を使用して、保存された情報を含めます コードを入れる.
<?xml version="1.0" encoding="UTF-8"?> <employment:employment put-code="739288" [...]> [...] </employment:employment>
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
APIは、アイテムが正しく更新されたことを示す200OKメッセージを返します。 別のメッセージが返される場合は、トラブルシューティングページを確認してください。
上のすべてのアイテム(伝記のテキストを除く) 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を呼び出し、アイテムの完全なデータを取得できます。 以下の項目は、 コードを入れる:
エンドポイント | 説明 |
/ address / [プットコード] | 個々の国または地域 |
/バイオグラフィー | 伝記フィールド:研究者のみが編集できるフリーテキスト領域 |
/ Education / [コードを入力] | 個人教育所属項目 |
/ email / [プットコード] | レコードに関連付けられている個々のメールアドレス |
/ employee / [プットコード] | 個人雇用所属項目 |
/ external-identifier / [プットコード] | 別のシステムでリンクされた個々の外部識別子 |
/ Funding / [プットコード] | 個別の資金調達活動 |
/ keywords / [プットコード] | 研究者とその研究に関連する個々のキーワード |
/ other-names / [プットコード] | 研究者が知っている個人の追加名 |
/ peer-review / [コードを入力] | 個々のピアレビュー活動 |
/ researcher-urls / [コードを入力] | 研究者の個人ページまたはプロフィール ページへの個別の外部リンク |
/ work / [コードを入れる] | 個別の調査研究 |
/ works / [put code1]、[put code2]、[put code3] | 個別のバルク研究(最大100) |
セクションエンドポイントとプットコードを使用すると、同じアクセストークンを使用して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
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 iDの場合、を指定してHTTPDELETEリクエストを行うことができます 関連エンドポイント、 一緒に ORCID iD、 保存されたアクセストークン、および保存されたプットコード。 一度に削除できるアイテムはXNUMXつだけで、クライアントによって追加されたアイテムのみを削除できます。 ユーザーが権限を取り消した場合でも、アイテムを削除できます。
この例の呼び出しは、レコードからプットコード「739288」の雇用アイテムを削除します。
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
さらに詳しく
永続的な識別子
内のほとんどのアイテム ORCID レコードにはXNUMXつ以上の永続的な識別子があります。 それらはXNUMXつの「フレーバー」、作業識別子と 組織識別子.
私たちを参照してください サポートされている識別子のリスト V3.0 API 用。 リクエストに応じて新しいタイプを追加することもあります ORCID レジストリにアイテムを追加するときにそれらを使用したいメンバー。
ORCID の使用をサポートします ROR識別子, グリッド識別子 と CrossrefFunderレジストリ の組織を明確にするための識別子 ORCID レコード。
詳細については、を参照してください。 組織識別子の操作
Ringgold の識別子は依然として存在しますが、 ORCID 1 年 2023 月 XNUMX 日時点のレジストリ、 ORCID レジストリで使用される RINGGOLD 組織識別子データベースの更新を受信できなくなり、その日以降に作成された RINGGOLD ID を処理または使用することもできなくなります。 私たちのを参照してください よくある質問 詳細は
グループ化
アイテムはにグループ化されます ORCID 識別子に基づくレコード。 追加したアイテムが既存のグループに追加されている場合があります。
で働く ORCID それらの識別子とそれらの識別子、作品との関係の両方に基づいてグループ化されます。 関係には次の XNUMX 種類があります。
- 自己:識別子はその作品のみを参照し、同じ識別子を持つ他の作品とグループ化できます
- の一部:作品はこの識別子の一部であり、他の作品とグループ化することはできません
- のバージョン:これらの識別子は作品の代替バージョンに適用され、自己およびバージョンの識別子とグループ化できます
- によって資金を供給:これらの識別子は、作業の資金に適用されます。 これらの識別子は、作業のグループ化には使用されません。
当社の API は、XSD でこれをサポートしています。各アイテムには、グループ内でのランクを示す表示インデックス属性があります。最も高い表示インデックスは、研究者が選択した優先アイテムです。API 経由で追加されたアイテムで、研究者によってランク付けされていないアイテムには表示インデックス 1 が付けられ、研究者によって変更されるまで、グループ内のデフォルトの優先ソースとして使用されます。表示インデックスは、アイテムを読み込むときの作業順序も決定します。 ORCID API を使用して記録します。
のグループ化に関する詳細については ORCID 記録、私たちを参照してください サポート記事.
透明性
の研究者による管理 ORCID レコードはのXNUMXつです ORCID'スコア 原則。 アイテムが追加されます ORCID 研究者のデフォルトの可視性設定で記録します。
可視性は、ユーザーが設定した可視性設定に基づいて、アイテムのプライバシー設定を示します。 APIを介して情報が投稿されるときに可視性タグが含まれている場合、それは無視されます。 むしろ、情報は、アカウント設定で設定されたユーザーのデフォルトの表示設定に従って投稿されます。
パブリック アイテムは、API を介して誰でも読み取ることができ、研究者のパブリック レコードに表示されます。信頼されたパーティ アイテムは、API を介して読み取り制限アクセス権を持つクライアントにのみ返されます。 それらは研究者の公的記録にはありません。 非公開アイテムは、研究者とアイテムのソースにのみ表示されます。API を介して返される非公開アイテムは、統合を介してレコードに追加されたもののみです。 の可視性設定の詳細 ORCID レジストリ.
ユーザー通知
とき ORCID メンバーがレコードのアイテムを追加または更新し、 ORCID これが発生したことをユーザーに通知します。
彼らは彼らの中で通知を受け取ります ORCID 受信トレイ。 上のデータに変更があるときはいつでも ORCID レコードを使用すると、ユーザーは、更新を実行しているクライアントの名前、変更日、および ORCID 更新されたレコード。 私たちを参照してください 通知の詳細については、ユーザーナレッジベース.

ORCID サンドボックスのレコードにも 機能している受信トレイ。 テストの受信トレイを定期的に確認することをお勧めします ORCID システムがデータ更新をスケジュールする方法を計画するときに記録します。