API 教程：添加和更新數據 ORCID 記錄

您可以 請求沙箱會員 API 憑證 建立並測試您的應用程式。這些憑證可讓您呼叫沙盒高級會員 API 來讀取、寫入和更新 ORCID 記錄。 任何人都可以免費訪問沙盒測試環境，即使您不是 ORCID 會員組織。

備註：如果您使用的是 ORCID 已支援的認證服務提供者係統 ORCID，您不需要註冊沙盒 API 憑證，除非您想嘗試 ORCID 沙盒環境中的整合功能。 

沙箱讓您可以創建測試用戶帳戶並開發您的集成，而不必擔心影響實時（生產）上的數據 ORCID 註冊表。 沙箱的行為方式與生產相同 ORCID 註冊與 一些例外.

創建測試帳戶

為了測試 ORCID API 和 API 調用，例如讀取和添加信息到 ORCID 記錄，您還需要創建一個測試 ORCID 記錄在沙箱中。 這可以通過用戶界面完成，就像在生產中一樣 ORCID 註冊表。 去 https://sandbox.orcid.org/register 並註冊一個帳戶。

郵寄者電子郵件地址

沙盒伺服器僅將電子郵件發送至 Mailinator (@mailinator.com) 電子郵件地址，以免無意中向郵件服務器發送垃圾郵件。 除非您使用@mailinator.com 地址，否則您不會收到驗證電子郵件或密碼重置通知，並且需要驗證才能對沙盒記錄進行任何手動編輯。 詳細了解他們免費使用的公共收件箱 並點選這裡。 如果您不想使用 Mailinator 地址，然後請記下您的用戶名和密碼（因為您將在測試時使用它們向您的應用程序授予授權），並聯繫我們請求驗證幫助。

Mailinator 是一種具有公共免費服務和私人付費服務的電子郵件服務。 對於測試，您可以使用完全免費的公共服務。 了解更多關於他們的等級 這裡.

Mailinator 是第三方服務，不受管理或維護 ORCID. 我們建議您在使用這些地址之前查看此服務的工作原理及其限制。

有兩種不同的更新範圍 - 一種用於傳記詳細信息，另一種用於活動。

ORCID 集成使用“3 legged OAuth”來驗證用戶並請求與他們的記錄交互的權限。 任何集成都可以使用公共 API 請求讀取權限。 ORCID 會員可以使用會員 API 請求更新權限。 它是這樣工作的：

• 您創建了一個特殊鏈接
• 單擊時，用戶將被發送到 ORCID
  • ORCID 要求用戶登錄
  • ORCID 要求用戶授予您的應用程序權限
  • ORCID 使用授權碼將用戶發送回您的系統
• 您的系統將該代碼交換為訪問令牌

定制的授權 URL 包括您的客戶信息，以及指定您希望訪問的他們記錄的特定區域的“範圍”。 登錄後，用戶授權與您的系統連接，並與授權代碼一起返回到您的登錄頁面。 然後使用此代碼獲取他們的 ORCID iD 以及對請求的範圍有效的訪問令牌。

建立授權鏈接並獲取授權碼

您可以透過指定 API 憑證的用戶端 ID 和關聯的登入頁面（重定向 URI）來建立授權連結。您可以透過設定來選擇請求哪些權限 範圍參數.

下面的示例請求讀取限制訪問數據的權限 ORCID 沙盒測試服務器。 在現實世界中，您會在您的網站上顯示此鏈接，或者在要求用戶進行身份驗證和授權時將其包含在電子郵件中。 但是，出於測試目的，您可以簡單地將其粘貼到您的網絡瀏覽器中。 用您的客戶信息替換括號中的數據，並確保刪除方括號！

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 和訪問令牌。 授權碼在使用時過期。 請求看起來像這樣 不能在網絡瀏覽器中製作，它必須由您的服務器製作。

 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 年到期。 令牌在到期前可以多次使用。

使用訪問令牌

三足訪問令牌鏈接到特定的 ORCID 記錄。 要使用它們，您可以將它們包含在您為讀取或更新該記錄而發出的 API 請求中。

當請求與某個人交互的權限時 ORCID 用戶的記錄中，您可以指定一個或多個“範圍”。 每個範圍都允許您執行某些操作，例如讀取記錄或更新特定部分。

三足（授權碼）範圍

3條腿 指獲取用戶許可所涉及的三個參與者； ORCID，您的系統和用戶自己。

/認證

此範圍用於收集 ORCID iD 並僅閱讀記錄中的公共信息。 所有其他 3-legged 範圍都包括身份驗證權限，因此如果要求任何其他訪問權限，則可以省略此範圍。 此範圍在成員或公共 API 上可用。

/read-limited（僅限會員 API）

此範圍用於訪問讀取公共和有限可見性項目上的 ORCID 記錄。 此範圍僅在成員 API 上可用。

/activities/update（僅限會員 API）

此範圍用於編寫、更新和刪除某個機構的隸屬關係、資助、作品、專業活動、研究資源和同儕審查部分中的項目。 ORCID 記錄。 此範圍僅在成員 API 上可用。

/person/update（僅限會員 API）

此範圍用於寫入、更新和刪除記錄的其他名稱、關鍵字、國家/地區、研究人員 URL、網站和個人外部標識符部分中的項目。 此範圍僅在成員 API 上可用。

Openid

當需要 id_token 時，OpenID 集成商使用此範圍。 當包含 openid 範圍時，註冊表將在令牌響應中返回一個 id_token 並授予客戶端訪問該用戶的用戶信息端點的權限。 此範圍在公共和成員 API 上可用。

請注意，“openid”作用域不像其他作用域那樣以“/”開頭 ORCID API 範圍。 這是因為“openid”範圍不是由 ORCID，而是由 OpenID Connect 規範定義。 請看我們的 OpenID 文檔 獲取更多訊息

多個範圍

通過在身份驗證 URL 中列出範圍並在每個範圍之間使用編碼空格，可以在單個交互中請求多個範圍，例如 scope=/read-limited%20/activities/update%20/person/update

完全訪問

如果您想要讀取和編輯記錄的完全訪問權限，請在您的身份驗證 URL 中包含三個範圍：/read-limited、/activities/update 和 /person/update。 在 URL 中，它們將顯示為 scope=/read-limited%20/activities/update%20/person/update

2 條腿（客戶端憑據）範圍

對於某些活動，您不必徵求用戶的許可。 直接從 請求兩個分支的 OAuth 範圍 ORCID API，不需要研究人員授予許可。 具有這些範圍的代幣有效期為 20 年並可重複使用

/讀公開

此範圍用於讀取有關單個的公共信息 ORCID iD，搜尋 ORCID 記錄或讀取摘要資訊（僅限會員 API）。此範圍可在會員或公共 API 上使用。

/ webhook

此範圍允許客戶端應用程序在 ORCID 記錄，以便在記錄更新時接收通知。 此範圍適用於高級 ORCID 內部使用。

項目（作品、就業、資金、同行評審等）可以添加到 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>

調用示例：Github

API 將返回一條 201 消息以指示該項目已正確發布，以及該項目 放代碼。 您的客戶將被列為 物品來源.

細味觀察 故障排除 頁面，如果返回不同的消息。 您將需要保存  存儲放置代碼和訪問令牌 進行任何更新或刪除項目。

An ORCID 記錄可能包含有關研究人員的工作、隸屬關係、資助、同行評審等的信息。

上的項目 ORCID 記錄可以分解為 斷言 連接 ORCID 具有活動或從屬關係的 iD 持有人. 這些斷言可以添加到 ORCID 由擁有記錄的研究人員或由研究人員授予許可的系統進行記錄。 我們稱添加斷言的實體為 ORCID 記錄 資源.

包機成本結構範例

遵循我們透明和公開的原則，我們認為能夠看到斷言的來源很重要——誰將這些信息添加到記錄中。 這是我們如何做到的：

1. 當研究人員（或其委託的 值得信賴的個人) 在他們的記錄中添加一個斷言， ORCID 自動將該人記錄為來源
2. 當研究人員批准的系統向記錄添加斷言時， ORCID 自動記錄系統所有者（一個 ORCID 成員）作為來源。

我們在用戶界面中顯示源名稱並使其在 API 中可用（及其唯一標識符）：

然而，研究信息工作流程可能比這更複雜，斷言的真正來源可能會被一個系統代表一個人或另一個系統添加項目無意中掩蓋。 為了確保透明度，我們需要區分誰在人和項目之間建立了聯繫，以及誰將項目添加到記錄中。 如上所述，無論誰將項目添加到 ORCID 記錄是 資源; 誰在兩者之間建立聯繫 ORCID iD 該項目是 斷言起源。

例如：

1. 研究人員將數據導入他們的 ORCID 從系統記錄，例如搜索和鏈接嚮導。 研究人員正在斷言將他們的 iD 與項目，所以他們是 斷言起源; 而係統是將斷言添加到 ORCID 記錄—— 資源
2. 研究人員與系統 A（系統 A 斷言來源)，它使用系統 B 提供的服務來更新 ORCID 記錄，使系統 B 成為 資源

我們鼓勵我們的社區採取措施來保存和共享有關斷言來源的信息，以便每個人都能從查看來源中受益。

欲了解更多信息，請訪問：

• 斷言保證途徑：它們是什麼以及它們為什麼重要？
• 啟用多個斷言的計劃 ORCID 註冊表

ORCID 成員可以更新他們之前添加到 ORCID 記錄。 一次只能更新一個項目，並且只能使用最初創建它的客戶端憑據進行更新。

為方便更新，請確保您 存儲放置代碼和訪問令牌 創建項目時。

格式化更新的項目 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

調用示例：GitHub

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>

此放置代碼可用於調用 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 iD，然後您可以發出 HTTP DELETE 請求，指定 相關終點， 隨著 ORCID ID， 存儲訪問令牌和存儲放置代碼. 一次只能刪除一項，您只能刪除客戶添加的項目。 即使用戶已撤銷權限，您也可以刪除項目。

此示例調用從記錄中刪除帶有放置代碼“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

示例調用：GitHub

請參閱我們的 支持的標識符列表 對於V3.0 API。 我們偶爾會應要求添加新類型 ORCID 在向註冊表添加項目時想要使用它們的成員。

ORCID 支持使用  ROR 標識符, 網格標識符 交叉引用資助者註冊 用於消除組織歧義的標識符 ORCID 紀錄。 

欲了解更多信息，請參閱 使用組織標識符

儘管 Ringgold 識別碼仍然存在於 ORCID 截至 1 年 2023 月 XNUMX 日， ORCID 我們不再接收註冊機構使用的 RINGGOLD 組織識別碼資料庫的更新，也無法處理或使用該日期之後建立的 RINGGOLD ID。 看看我們的 常見問題 更多信息

在...工作 ORCID 根據他們的標識符和這些標識符與作品的關係組合在一起。 有四種類型的關係：

• 自：標識符僅指該作品，可以與具有相同標識符的其他作品分組
• 的一部分：作品是此標識符的一部分，不能與其他作品分組
• 版本號：這些標識符適用於作品的替代版本，並且可以與標識符的自我和版本分組
• 資助：這些標識符適用於工作的資金。 這些標識符不用於對作品進行分組。

我們的 API 在 XSD 中提供了對此的支援。每個項目都有一個顯示索引屬性，指示其在其群組中的排名。顯示指數最高的項目是研究者選擇的首選項目。透過 API 新增且尚未由研究人員排名的項目的顯示索引為 1，並用作群組內的預設首選來源，直到研究人員進行更改。顯示索引也決定了讀取時的工作順序 ORCID 使用 API 進行記錄。

有關分組的更多信息 ORCID 記錄，請參閱我們的 支持文章.

可見性指示項目的隱私設置，基於用戶設置的可見性首選項。 如果在通過 API 發布信息時包含可見性標記，它將被忽略。 相反，信息將根據用戶在其帳戶首選項中設置的默認可見性首選項發布。

任何人都可以通過 API 讀取公共項目，並顯示在研究人員的公共記錄中，可信方項目僅通過 API 返回給具有讀取限制訪問權限的客戶； 他們不在研究人員的公共記錄中。 私有項目僅對研究人員和項目來源可見——通過 API 返回的唯一私有項目是那些通過您的集成添加到記錄中的項目 有關可見性設置的更多信息 ORCID 註冊表.

他們收到通知 ORCID 收件箱. 每當數據發生變化時 ORCID 記錄，用戶會收到通知，其中包含有關更改的基本信息，包括執行更新的客戶端名稱、更改日期以及更改的項目 ORCID 已更新的記錄。 查看我們的 用戶知識庫，了解有關通知的更多信息.  

ORCID 沙箱上的記錄也有 功能收件箱. 我們建議您定期查看測試的收件箱 ORCID 在規劃系統如何安排數據更新時記錄。