ORCID 提供多種 API,允許您的系統連接到 ORCID 註冊表,包括讀取和寫入 ORCID 記錄。 某些 API 函數可供任何人免費使用(公開API); 其他人只能使用 ORCID 會員組織(會員和高級會員 API)。 任何人都可以在我們的沙盒測試服務器上自由測試我們的任何 API。
在你開始之前
當您開始進行集成規劃時,您應該考慮:
- 你想用 ORCID API——請訪問我們的 工作流程.
- 無論您的組織是 已經是 ORCID 會員 或是 計劃成為一名. 僅有的 ORCID 成員可以添加項目 ORCID 紀錄。
- 您使用的系統是否已經支持 ORCID. 如果你是,它可能就像配置你的系統一樣簡單 ORCID.
- 您將如何與您的研究人員就正在實施的更改進行交流,您需要從他們那裡得到什麼,給他們帶來的好處,以及他們需要做什麼。 訪問我們的 外聯資源 有關如何圍繞您的新集成開展交流活動的想法的頁面。
註冊沙箱憑據並創建測試 ORCID iD
我們要求您首先構建與 ORCID 砂箱 防止在測試期間影響生產註冊表或您自己的系統上的任何數據。
您可以 請求沙箱會員 API 憑證 構建和測試您的應用程序。 這些憑據允許您調用沙箱成員 API 以讀取、寫入和更新 ORCID 記錄。 任何人都可以免費訪問沙盒測試環境,即使您不是 ORCID 會員組織。
備註: 如果您使用的第三方系統已經支持 ORCID,您可能不需要註冊沙盒 API 憑據。
沙箱讓您可以創建測試用戶帳戶並開發您的集成,而不必擔心影響實時(生產)上的數據 ORCID 註冊表。 沙箱的行為方式與生產相同 ORCID 註冊與 一些例外.
創建測試帳戶
為了測試 ORCID API 和 API 調用,例如讀取和添加信息到 ORCID 記錄,您還需要創建一個測試 ORCID 記錄在沙箱中。 這可以通過用戶界面完成,就像在生產中一樣 ORCID 註冊表。 去 https://sandbox.orcid.org/register 並註冊一個帳戶。
郵寄者電子郵件地址
沙箱服務器僅將通知電子郵件發送至 Mailinator (@mailinator.com) 電子郵件地址,以免無意中向郵件服務器發送垃圾郵件。 除非您使用@mailinator.com 地址,否則您不會收到驗證電子郵件或密碼重置通知,並且需要驗證才能對沙盒記錄進行任何手動編輯。 詳細了解他們免費使用的公共收件箱 並點選這裡。 如果您不想使用 Mailinator 地址,然後請記下您的用戶名和密碼(因為您將在測試時使用它們向您的應用程序授予授權),並聯繫我們請求驗證幫助。
Mailinator 是一種具有公共免費服務和私人付費服務的電子郵件服務。 對於測試,您可以使用完全免費的公共服務。 了解更多關於他們的等級 点击這裡.
Mailinator 是第三方服務,不受管理或維護 ORCID. 我們建議您在使用這些地址之前查看此服務的工作原理及其限制。
確定您需要的用戶權限
ORCID 會員 API 可用於讀取、添加或更新用戶的信息 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 上可用。
/ webhook
此範圍允許客戶端應用程序在 ORCID 記錄,以便在記錄更新時接收通知。 此範圍適用於高級 ORCID 內部使用。 如果您不是高級會員,但希望在開發者沙盒中測試此功能,請 聯繫我們 ORCID 社群 .
- 在過去 ORCID 支持其他範圍,現在已經 逐步淘汰.
- 你可以找出來 在此處添加或更新特定部分需要哪些範圍.
確保您可以安全地存儲數據
重要的是您的系統能夠存儲信息 以安全的方式.
集成需要存儲的不僅僅是 ORCID 記錄。 您的系統需要能夠:
- 接受並存儲 ORCID iD:您的系統需要知道 iD 的 ORCID 記錄更新。 將其與研究人員的信息存儲在一起。 我們的建議是存儲完整的 https URI: https://orcid.org/0000-0001-5727-2427.
- 接受並存儲持久化 訪問令牌 和 刷新令牌:訪問令牌可用於讀取和更新記錄,以及指示 iD 已通過身份驗證。 持久性令牌的有效期大約為 20 年,或者直到用戶撤銷它們為止。 刷新令牌可用於創建具有相同或有限範圍的新訪問令牌。 將令牌與研究人員的信息一起存儲。 我們還建議您將 令牌範圍,以及‚令牌到期.
- 接受並存儲 把代碼 (如果更新 ORCID 記錄):您添加到 ORCID 註冊表將返回一個放置代碼 ORCID 應用程序接口。 將此放置代碼與系統中的項目一起保存,這是您識別需要讀取或更新的項目的方式。
- 記錄交互:您的系統應該記錄對 ORCID 收到的 API 和響應。 這是必要的所以 ORCID 如果以後出現問題,可以提供幫助。
- 當交互未按預期進行時,提供錯誤消息和支持聯繫人。
與 ORCID 團隊展示您的應用程序如何工作
在您的集成上線之前 ORCID 生產註冊表,我們的參與團隊將仔細檢查您在沙箱上構建的所有內容是否也適用於生產。 如果您使用的是內置系統 ORCID 支持,這一步可以跳過。
會員組織要求 ORCID 通過完成生產(實時)服務器上的成員 API 憑據 生產會員API客戶端申請表. 在發布生產會員 API 憑證之前, ORCID 參與團隊將審查您在 ORCID 沙箱。 這讓我們有機會看到您構建的出色集成並提供工作流程改進,以及檢查所有集成是否符合我們的最佳實踐。
要提供您的系統的演示,您需要設置與 ORCID 沙箱 ORCID 團隊可以預覽。 有幾種方法可以共享您的工作沙箱集成:
- 推薦: 現場演示: 聯繫我們安排現場演示. 我們將提供會議軟件,允許您共享您的屏幕以演示您的集成。 這也讓我們有機會更多地了解您的系統是如何工作的,以及您如何解釋您的系統的好處 ORCID 集成,因此我們可以為您和您的用戶提供更好的支持。
- 測試地點: 如果您的開發站點是公開的, 把網址發給我們 以及訪問系統的測試憑據(如果需要)和描述如何使用系統的說明 ORCID 特徵。 提供額外的文檔以驗證我們無法從用戶端看到的內容,例如使用的 API 版本、您的系統存儲了哪些數據等。
- 截屏視頻或屏幕截圖(推薦用於 ORCID-需要演示的啟用系統): 發送錄音或一組截圖 帶有描述,清楚地解釋和演示您的集成在每個步驟中的工作方式,包括如果用戶拒絕訪問或斷開其 iD 連接會發生什麼。 請務必提供額外的文檔來驗證我們無法從用戶端看到的任何內容,例如使用的 API 版本和數據的存儲方式。¬¨‚
如果您正在使用其中一種 ORCID- 無需演示的啟用系統,您可以直接 請求生產會員 API 憑證. 請務必在說明中指定您使用的系統(以及,如果適用,版本)。
我們希望所有成員集成都能滿足許多要求。 這 ORCID 作為集成審查過程的一部分,團隊將確保滿足這些要求。
- 使用 OAuth的 認證 ORCID iDs(不允許用戶搜索或輸入 ORCID 身份證。)
- 包括一個 ORCID 品牌按鈕或鏈接 在您的站點上啟動 iD 身份驗證。
- 根據我們的提示顯示 OAuth 授權屏幕 方針
- 將 HTTPS 用於您網站的重定向 URI 和 ORCID API調用
- 接受並存儲在令牌交換中返回的所有數據以及您系統中的用戶數據
- 使用適當 範圍 和 請求方法 (例如 POST 調用添加新信息和 PUT 調用更新現有信息)
- 公開顯示已認證的 ORCID 身份證。 應按照我們的要求顯示 ID 商標和 iD 顯示指南。
在生產服務器上請求憑據
一旦您的集成通過審核,您就可以申請成員 API 憑證 ORCID 團隊,或者如果您使用的是具有內置功能的服務提供商系統 ORCID 積分。
您需要填寫 用於註冊客戶端應用程序的表單. 以下是請求字段的快速概覽:
的注意事項 ORCID 員工: 使用這個字段讓 ORCID 了解您是否正在使用供應商系統,是否已審查集成等。
聯繫郵箱地址:我們會將憑據發送到此地址。 這應該是我們在集成方面一直與之合作的聯繫人或我們為您的組織持有的技術聯繫人。
用於接收 PIN 以訪問憑據的聯繫人:我們以安全的方式向您發送完整的憑據。 我們將向此聯繫人發送用於訪問您的 API 憑據的密碼。 這需要是與之前列出的聯繫人不同的聯繫人。
您的客戶端應用程序的簡短描述:此文本將顯示在授權屏幕上,並帶有問號圖標給您的集成用戶。 需要對您的集成進行簡短描述。
您的應用程序主頁的 URL:顯示為用戶內受信任組織列表上的鏈接 ORCID 受信任方頁面。 這應該是返回您的組織或應用程序主頁的鏈接。
客戶端的 OAuth2 重定向 URI 或回調 URL:您的 Web 應用程序中允許的 URL,用戶在授權訪問其訪問權限後將返回到該 URL ORCID 記錄數據。 對於生產(實時)服務器客戶端,所有重定向 URI 都必須是 HTTPS。
提出請求後,會通過手動流程向您發放憑據,您將收到一封電子郵件給您的客戶 iD 和客戶機密。 通常,這些請求會在 48 小時內得到處理。
將您的申請轉移到 ORCID 生產登記處
獲得憑據後,您就可以開始使用它了。 如果您想在向公眾發布之前測試您的集成,請使用測試人員自己的 ORCID 記錄或同事的 ORCID 記錄。
啟動——並讓所有人知道
使應用程序上線並不是最後一步——您需要繼續與您的用戶溝通,以便他們知道連接他們的 ORCID iD 快速輕鬆地連接到您的系統。 有效的集成包含技術組件(本指南涵蓋)和社交組件。 研究人員需要被告知什麼 ORCID 是,為什麼您要求訪問他們的 ORCID 記錄,以及您將如何處理他們的數據。
- 創建溝通時間表:確保利益相關者了解您的 ORCID 在您啟動之前做好項目。
- 結合使用自上而下和自下而上的溝通方式。
- 推廣你的 ORCID 經常和不同的受眾進行整合。
- 創建本地資源 為您的用戶提供支持,例如常見問題解答、libguides、網頁、教程和視頻。
- 指定當地聯繫人 ORCID-相關問題。