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-legged(客户端凭据)范围
对于某些活动,您不必征得用户许可。 直接从 ORCID API,不需要研究人员授予许可。 具有这些范围的令牌的有效期为 20 年并可重复使用
/读公开
此范围用于读取有关单个的公共信息 ORCID iD 或搜索 ORCID 记录。 此范围在成员或公共 API 上可用。
/ webhook
此范围允许客户端应用程序在 ORCID 记录,以便在记录更新时接收通知。 此范围适用于高级 ORCID 内部使用。 如果您不是高级会员,但希望在开发者沙盒中测试此功能,请 CONTACT 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-相关问题。