本教程将引导您阅读有关 ORCID 使用公共或成员 API 记录。 它基于 3.0 版 ORCID 消息架构。
获取一些客户端凭据
客户端凭据是您的应用程序/网站将用于访问 ORCID API。 任何人都可以注册只读的公共 API 凭证, ORCID 会员可以注册会员API。
我们建议开发人员在 沙盒测试服务器 在使用生产版本之前。 以下是有关如何在沙盒和生产环境中注册公共 API 凭证的步骤。
- 登录你的 ORCID 记录:
生产服务器: https://orcid.org/signin
沙盒测试服务器: https://sandbox.orcid.org/signin - 在右上角点击你的名字
- 点击 开发者工具 从菜单选项
请注意: 为了访问开发人员工具,您必须验证您的电子邮件地址。 如果您尚未验证您的电子邮件地址,系统会提示您进行验证,然后才能注册公共 API 凭据 - 阅读并同意‘ORCID 公共客户服务条款
- 点击“注册 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 已在生产中接受
- 已注册的域 必须 与使用的域完全匹配,包括子域
- 尽可能完整注册所有重定向 URI。 这是最安全的选项,也是我们推荐的选项。 有关重定向 URI 的更多信息,请参阅我们的 重定向 URI 常见问题解答
保存您的申请
填写完申请表并添加重定向 URI 后,您可以保存您的申请。
- 单击“保存我的应用程序并生成我的客户端” ID 和秘密'
您将被引导回开发人员工具页面,该页面现在将包含您的公共 API 客户端凭据
更新您的凭据
更改您的申请信息非常简单。
- 编辑相关信息,然后点击“保存申请”
使用您的凭据
现在您已拥有凭据,是时候开始使用 ORCID 公共API!
请注意,如果您成为会员,我们可以将您的凭据传输到会员 API 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。 这是通过 OAuth 完成的。 注意:
- 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 记录总结。
要获得 /read-limited 访问权限,您必须征得研究人员的许可。 您可以使用 OAuth 执行此操作。 具体来说, ”三足OAuth“。
有关更多信息,请参见我们的 API 教程:读取数据 ORCID 记录
ORCID 集成使用“3legged 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 和访问令牌。 授权码在使用时过期。 请求看起来像这样 不能在网络浏览器中制作,它必须由您的服务器制作。
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 记录分为许多部分。 您可以阅读整个摘要,也可以只阅读您感兴趣的部分。
此示例调用检索完整的摘要 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 记录 |
/人 | 传记部分 ORCID 记录,包括通过下面的 /researcher-urls |
/概括 | 已验证和自断言项目的摘要视图 ORCID 记录(仅适用于会员 API) |
/地址 | 研究人员所在国家或地区 |
/电子邮件 | 与记录关联的电子邮件地址 |
/外部标识符 | 其他系统中链接的外部标识符 |
/关键词 | 与研究人员及其工作相关的关键词 |
/其他名称 | 研究人员知道的其他名字 |
/个人资料 | 个人详细信息:研究人员姓名、信用(出版)姓名和传记 |
/研究人员网址 | 链接到研究人员的个人或个人资料页面 |
/活动 | 活动部分摘要 ORCID 记录,包括通过下面的 /works。 |
/教育 | 教育机构 |
/就业 | 就业关系 |
/资金 | 资助活动摘要 |
/同行评审 | 同行评审活动总结 |
/作品 | 研究工作总结 |
/研究资源 | 研究资源总结 |
/服务 | 服务摘要 |
/资格 | 资质概要 |
/会员 | 会员概要 |
/区别 | 区别总结 |
/邀请职位 | 受邀职位摘要 |
使用令牌访问 API
现在您有了访问令牌,您可以进行 API 调用以获取 XML 或 JSON 格式的数据。
上的所有项目(除了传记文本) 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 以检索项目的完整数据。 可以使用以下项目查询 放代码:
端点 | 产品描述 |
/地址/[放置代码] | 个别国家或地区 |
/传 | 传记字段:只有研究人员可以编辑的自由文本区域 |
/教育/[输入代码] | 个人教育隶属项目 |
/email/[输入代码] | 与记录关联的个人电子邮件地址 |
/就业/[放代码] | 个人雇佣关系项目 |
/外部标识符/[放置代码] | 另一个系统中的单独链接的外部标识符 |
/funding/[放置代码] | 个人资助活动 |
/keywords/[输入代码] | 与研究人员及其工作相关的单个关键字 |
/other-names/[输入代码] | 研究人员知道的个人附加名称 |
/peer-review/[放置代码] | 个人同行评审活动 |
/researcher-urls/[放置代码] | 指向研究人员个人或个人资料页面的个人外部链接 |
/work/[放置代码] | 个人研究工作 |
/works/[放代码1],[放代码2],[放代码3] | 批量个人研究作品(最多 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 基于其标识符的记录。 您可能会发现您阅读的项目是一个组的一部分。
在...工作 ORCID 根据它们的标识符和这些标识符与作品的关系组合在一起。 有四种类型的关系:
- 自:标识符仅指该作品,可以与具有相同标识符的其他作品分组
- 的一部分:作品是此标识符的一部分,不能与其他作品分组
- 版本:这些标识符适用于作品的替代版本,并且可以与标识符的自我和版本分组
- 受资助:这些标识符适用于工作的资金。 这些标识符不用于对作品进行分组。
我们的 API 在 XSD 中为此提供了支持。 每个项目都有一个显示索引属性,指示其在其组中的排名。 最高显示指数是研究者选择的首选项目,通过API添加的未由研究人员排名的项目显示指数为0。显示指数也决定了阅读时的工作顺序 ORCID 记录。
有关分组的更多信息 ORCID 记录,请参阅我们的 支持文章.
关于内容类型的说明
ORCID 支持多种内容类型,包括 XML 和多种 JSON。 您可以通过在 API 请求中包含“接受标头”来询问您的首选类型。 这称为“内容协商”。
ORCID 注册表支持“内容协商”。 这意味着机器和其他系统可以询问 ORCID 不同格式的人员元数据注册表。
其中一种格式是 JSON-LD,它使用 schema.org 词汇,特别是 人物类型,我们将其与作品、组织和其他标识符联系起来。 我们还支持 XML、JSON、RDF XML 和海龟,并实现了跨域资源共享 (CORS),使我们的数据易于访问。
- 点击查看 博客文章概述 ORCID 和 schema.org
- 看看我们的 内容协商技术文档
关于不存在的说明 ORCIDs
使用 cURL 搜索用户,如下所示:
curl -iL https://orcid.org/0000-0000-0000-0000
即使用户返回 200 才不是 存在。 为避免这种情况,请在通话中使用内容协商,如下所示:
curl -iL -H 'Accept: application/xml' https://orcid.org/0000-0000-0000-0000