本教程将引导您完成将信息添加到 ORCID 记录、格式化数据 ORCID 消息架构,以及更新或删除您之前添加到 ORCID 记录。
获取一些客户端凭据
客户端凭据是您的应用程序/网站将用于访问 ORCID API。 任何人都可以注册只读的公共 API 凭证, ORCID 会员可以注册会员API。
您将需要会员 API 凭据 沙盒测试服务器,以及测试记录 ORCID 沙箱以测试添加和更新项目到 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 记录,您必须首先获得记录所有者的许可。 仅有的 ORCID 成员可以请求更新权限,这是通过请求“/活动/更新”和/或“/人/更新” 使用 OAuth 的范围。
有两种不同的更新范围 - 一种用于传记详细信息,另一种用于活动。
范围 | 产品描述 | API端点 |
/人/更新 | 个人资料-左栏 ORCID 记录用户界面。 | /地址 /外部标识符 /关键词 /其他名称 /研究人员网址 |
/活动/更新 | 研究活动数据-右栏 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 请求中。
当请求与某个人交互的权限时 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 会员 API。 它们将与您的客户名称一起作为项目的“来源”出现。
项目(作品、就业、资金、同行评审等)可以添加到 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>
API 将返回一条 201 消息以指示该项目已正确发布,以及该项目 放代码. 您的客户将被列为 物品来源.
查看我们的 故障排除 页面,如果返回不同的消息。 您将需要保存 存储放置代码和访问令牌 进行任何更新或删除项目。
An ORCID 记录可能包含有关研究人员的工作、隶属关系、资金、同行评审等的信息。
上的项目 ORCID 记录可以分解为 断言 连接 ORCID 具有活动或从属关系的 iD 持有者. 这些断言可以添加到 ORCID 由拥有记录的研究人员或由研究人员授予许可的系统进行记录。 我们称添加断言的实体为 ORCID 记录 资源.
国际私人包机价格项目范例
遵循我们透明和公开的原则,我们认为能够看到断言的来源很重要——谁将这些信息添加到记录中。 这是我们如何做到的:
- 当研究人员(或其委托的 值得信赖的个人) 在他们的记录中添加一个断言, ORCID 自动将该人记录为来源
- 当研究人员批准的系统向记录添加断言时, ORCID 自动记录系统所有者(一个 ORCID 成员)作为来源。
我们在用户界面中显示源名称并使其在 API 中可用(及其唯一标识符):
然而,研究信息工作流程可能比这更复杂,断言的真正来源可能会被一个系统代表一个人或另一个系统添加项目无意中掩盖。 为了确保透明度,我们需要区分谁在人和项目之间建立了联系,以及谁将项目添加到记录中。 如上所述,无论谁将项目添加到 ORCID 记录是 资源; 谁在两者之间建立联系 ORCID iD 该项目是 断言起源。
例如:
- 研究人员将数据导入他们的 ORCID 从系统记录,例如搜索和链接向导。 研究人员正在做出将他们的断言联系起来的断言 iD 与项目,所以他们是 断言起源; 而系统是将断言添加到 ORCID 记录—— 资源
- 研究人员与系统 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
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 以检索项目的完整数据。 可以使用以下项目查询 放代码:
端点 | 产品描述 |
/地址/[放置代码] | 个别国家或地区 |
/传 | 传记字段:只有研究人员可以编辑的自由文本区域 |
/教育/[输入代码] | 个人教育隶属项目 |
/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 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
更多信息
持久标识符
一个范围内的大多数项目 ORCID 记录具有一个或多个持久标识符。 它们有两种“风格”,工作标识符和 组织标识符.
分组
项目被分组在一起 ORCID 基于其标识符的记录。 您可能会发现您添加的项目已添加到现有组中。
在...工作 ORCID 根据它们的标识符和这些标识符与作品的关系组合在一起。 有四种类型的关系:
- 自:标识符仅指该作品,可以与具有相同标识符的其他作品分组
- 的一部分:作品是此标识符的一部分,不能与其他作品分组
- 版本:这些标识符适用于作品的替代版本,并且可以与标识符的自我和版本分组
- 受资助:这些标识符适用于工作的资金。 这些标识符不用于对作品进行分组。
我们的 API 在 XSD 中为此提供了支持。 每个项目都有一个显示索引属性,指示其在其组中的排名。 最高显示指数是研究者选择的首选项目,通过API添加的未由研究人员排名的项目显示指数为0。显示指数也决定了阅读时的工作顺序 ORCID 记录。
有关分组的更多信息 ORCID 记录,请参阅我们的 支持文章.
提升品牌曝光性
研究人员控制 ORCID 记录是其中之一 ORCID'分数 原则. 项目被添加到 ORCID 具有研究人员默认可见性设置的记录。
可见性指示项目的隐私设置,基于用户设置的可见性首选项。 如果在通过 API 发布信息时包含可见性标记,它将被忽略。 相反,信息将根据用户在其帐户首选项中设置的默认可见性首选项发布。
任何人都可以通过 API 读取公共项目,并显示在研究人员的公共记录中,可信方项目仅通过 API 返回给具有读取限制访问权限的客户; 他们不在研究人员的公共记录中。 私有项目仅对研究人员和项目来源可见——通过 API 返回的唯一私有项目是那些通过您的集成添加到记录中的项目 有关可见性设置的更多信息 ORCID 注册表.
用户通知
当 ORCID 成员添加或更新记录上的项目, ORCID 通知用户这已经发生。
他们收到通知 ORCID 收件箱. 每当数据发生变化时 ORCID 记录,用户会收到通知,其中包含有关更改的基本信息,包括执行更新的客户端名称、更改日期以及更改的项目 ORCID 已更新的记录。 查看我们的 用户知识库,了解有关通知的更多信息.
ORCID 沙箱上的记录也有 功能收件箱. 我们建议您定期查看测试的收件箱 ORCID 在规划系统如何安排数据更新时记录。