API 教程：讀取記錄上的數據

我們建議開發人員在 沙盒測試服務器 在使用生產版本之前。 以下是有關如何在沙盒和生產環境中註冊公共 API 憑證的步驟。

• 登錄你的 ORCID 記錄：
  生產服務器： https://orcid.org/signin
  沙盒測試服務器： https://sandbox.orcid.org/signin
• 在右上角點擊你的名字
• 點擊 開發者工具 從菜單選項
  注意： 為了訪問開發人員工具，您必須驗證您的電子郵件地址。 如果您尚未驗證您的電子郵件地址，系統會提示您進行驗證，然後才能註冊公共 API 憑據
• 閱讀並同意‘ORCID 公共 API 服務條款
• 點擊“註冊 ORCID 公共 API 憑證”按鈕。

填寫申請詳情表

• 註冊公共 API 憑證後，您將被引導回開發人員工具（https://orcid.org/developer-tools or https://sandbox.orcid.org/developer-tools).
• 您需要填寫提交的申請詳細信息表以註冊新申請。
  • 名稱：您的應用程序的名稱。 當用戶授予您的應用程序權限以獲取他們的權限時，這將顯示給用戶 ORCID iD，它將顯示在他們的 受信任組織列表. 我們建議使用您的組織或服務的名稱（例如期刊名稱）。
  • 申請網址： 用戶可以訪問該網站以了解有關您的應用程序的更多信息。 這也將顯示在他們的 受信任組織列表.
  • 應用說明：有關您正在開發的應用程序以及您將如何使用用戶的應用程序的信息 ORCID ID。 這將在 OAuth 屏幕上向用戶顯示。

將 重定向 URI

用戶授權您的應用程序後，他們將返回到您指定的 URI。 您必須提前提供這些 URI，否則您的集成用戶將遇到錯誤。

• 在提供的框中輸入您的重定向 URI
• 如果您需要輸入超過 1 個重定向 URI，請單擊“添加另一個重定向 URI”

請注意：

• 只 HTTPS URI 已在生產中接受
• 已註冊的域 必須（MUST） 與使用的域完全匹配，包括子域
• 盡可能完整註冊所有重定向 URI。 這是最安全的選項，也是我們推薦的選項。 有關重定向 URI 的更多信息，請參閱我們的 重定向 URI 常見問題解答

保存您的申請

填寫完申請表並添加重定向 URI 後，您可以保存您的申請。

• 點擊“儲存我的申請並產生我的客戶端 ID 和密碼”

您將被引導回開發人員工具頁面，該頁面現在將包含您的公共 API 客戶端憑據

更新您的憑據

更改您的申請信息非常簡單。

• 編輯相關信息，然後點擊“保存申請”

使用您的憑據

現在您已擁有憑據，是時候開始使用 ORCID 公共API！

請注意，如果您成為會員，我們可以將您的憑據傳輸到會員 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. 我們建議您在使用這些地址之前查看此服務的工作原理及其限制。

任何擁有公共或成員 API 憑證的人都可以收到 /讀公開 訪問令牌。 要獲得令牌，您可以調用 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 的整合商可以使用 /讀公開 閱讀範圍 ORCID 記錄總結。

要獲得/讀取限制的訪問權限，您必須徵求研究人員的許可。 您可以使用 OAuth 來執行此操作。 具體來說， ”三足OAuth“。

有關更多信息，請參見我們的 API 教程：讀取數據 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 請求中。

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

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

此示例調用檢索完整的摘要 ORCID 使用沙盒服務器上的成員 API 以 XML 格式記錄。 您需要訪問令牌才能向公共或成員 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 根據他們的標識符和這些標識符與作品的關係組合在一起。 有四種類型的關係：

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

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

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

ORCID 註冊表支持“內容協商”。 這意味著機器和其他系統可以詢問 ORCID 不同格式的人員元數據註冊表。

其中一種格式是 JSON-LD，它使用 schema.org 詞彙，特別是 人物類型，我們將其與作品、組織和其他標識符聯繫起來。 我們還支持 XML、JSON、RDF XML 和turtle，並實現了跨域資源共享 (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