使用E-utility URL

所有E-utility请求都应发送到以下字符串开头的URL：

https://eutils.ncbi.nlm.nih.gov/enterz/eutils/

这些URL将请求定向到仅由E-utilities使用的服务器，这些服务器经过优化，可为用户提供最佳性能。

电子工具URL请求的频率、时间和注册

为了避免E-utility服务器过载，NCBI建议用户每秒发布的URL请求不要超过三次，并将大型作业限制在周末或工作日东部时间9:00 PM至5:00 AM之间。如果不遵守此策略，可能会导致IP地址被阻止访问NCBI。如果NCBI阻止IP地址，则不会恢复服务，除非访问电子实用程序的软件开发人员注册了工具和电子邮件具有NCBI的参数。的值工具应该是一个没有内部空间的字符串，该字符串唯一标识生成请求的软件。的价值电子邮件应该是软件开发人员的完整有效电子邮件地址，而不是第三方最终用户的电子邮件地址。的价值电子邮件将仅用于在NCBI发现违反我们政策的请求时联系开发人员，我们将在阻止访问之前尝试此类联系。此外，开发人员可能会要求电子邮件添加到E-utility邮件列表中，该邮件列表提供软件更新公告、已知错误和其他影响E-utilities的策略更改。注册工具和电子邮件值，只需发送电子邮件至vog.hin.mln.ibcn@seitilitue公司包括所需的值以及开发人员或创建软件的组织的名称。一旦NCBI与开发人员建立通信，就会收到以下值工具和电子邮件并在中验证电子邮件地址电子邮件，块将被提升。一次工具和电子邮件值已注册，则来自该软件包的所有后续E-utility请求都应包含这两个值。请注意，仅为工具和电子邮件在请求中不足以遵守本政策；这些值必须向NCBI注册。来自任何缺少以下注册值的IP的请求工具和电子邮件违反上述使用策略的可能会被阻止。软件开发人员可以注册以下值工具和电子邮件我们鼓励您随时这样做。

API密钥

自2018年12月1日起，NCBI提供了API密钥，以增强对电子实用程序的支持访问级别。如果没有API密钥，任何站点（IP地址）每秒向E-utilities发送3个以上的请求都将收到错误消息。通过包含API密钥，默认情况下，一个站点每秒最多可以发布10个请求。可根据要求提供更高的价格(vog.hin.mln.ibcn@seitilitue公司). 用户现在可以从其NCBI帐户的设置页面获取API密钥（要创建帐户，请访问http://www.ncbi.nlm.nih.gov/账户/). 创建密钥后，用户应将其分配给api密钥参数。

包含API密钥的请求示例：
summary.fcgi？db=pubmed&id=123456&api_key=ABCD12345

超过速率时的错误消息示例：
{“错误”：“超出API速率限制”，“计数”：“11”}

每个NCBI帐户只允许一个API密钥；然而，用户可以随时请求新密钥。此类请求将使与该NCBI帐户关联的任何现有API密钥无效。

最小化请求数量

如果一个任务需要搜索和/或下载大量记录，那么使用Entrez History批量上传和/或检索这些记录要比对每条记录使用单独的请求更有效。请参阅第3章中的应用3例如。使用一个EPost请求可以上传数千个ID，使用一个EFetch请求可以下载数百条记录。

免责声明和版权问题

如果您在软件中使用电子实用程序，请参阅NCBI的免责声明和版权声明(https://www.ncbi.nlm.nih.gov/About/disclaimer.html)必须对产品的用户来说是显而易见的。请注意，PubMed中的摘要可能包含受美国和外国版权法保护的材料。所有复制、重新分发或商业使用此信息的人都应遵守版权所有者声明的条款和条件。传输或复制超出版权法规定的合理使用（PDF）允许范围的受保护项目需要获得版权所有者的书面许可。NLM不提供有关版权材料分发的法律建议。请咨询您的法律顾问。如果您希望对PubMed数据进行大型数据挖掘项目，可以下载数据库的本地副本，网址为https://www.nlm.nih.gov/databases/download/pubmed_medine.html（网址：https://www.nlm.nih.gov/databases/download/pubmed_medine.html）.

处理URL中的特殊字符

为E-utilities构建URL时，请为除&WebEnv之外的所有参数使用小写字符。E-utility URL中的URL参数没有要求的顺序，通常会忽略空值或不适当的参数。避免在URL中放置空格，尤其是在查询中。如果需要空格，请使用加号（+）而不是空格：

不正确：&id=352251234
对的：&id=35225125234

不正确：&term=生物醇mrna[属性]和小鼠[生物体]
对的：&term=生物醇+mrna[属性]+AND+小鼠[生物体]

其他特殊字符，如引用历史记录服务器上的查询键时使用的引号（“）或#符号，应通过其URL编码表示（%22表示“；%23表示#）。

不正确：&term=#2+AND+“基因组中的基因”[属性]
对的：&term=%232+AND+%22基因+in+基因组%22[属性]

EInfo（数据库统计）

eutils.ncbi.nlm.nih.gov/enterz/eutils/einfo.fcgi

提供给定数据库每个字段中索引的记录数、数据库上次更新的日期以及从数据库到其他Entrez数据库的可用链接。

ESearch（文本搜索）

eutils.ncbi.nlm.nih.gov/enterz/eutils/esearch.fcgi

使用给定数据库中匹配的UID列表（供以后在ESummary、EFetch或ELink中使用）以及查询的术语翻译来响应文本查询。

EPost（UID上传）

eutils.ncbi.nlm.nih.gov/enterz/eutils/epost.fcgi

接受给定数据库中的UID列表，将集合存储在历史服务器上，并使用上载数据集的查询键和web环境进行响应。

E摘要（文档摘要下载）

eutils.ncbi.nlm.nih.gov/enterz/eutils/esummary.fcgi

用相应的文档摘要响应给定数据库中的UID列表。

EFetch（数据记录下载）

eutils.ncbi.nlm.nih.gov/enterz/eutils/efetch.fcgi

用指定格式的相应数据记录响应给定数据库中的UID列表。

ELink（Entrez链接）

eutils.ncbi.nlm.nih.gov/enterz/eutils/elink.fcgi

用同一数据库中的相关UID列表（和相关性得分）或另一Entrez数据库中的链接UID列表响应给定数据库中的UID列表；检查一个或多个UID列表中是否存在指定链接；为特定UID和数据库创建指向主LinkOut提供程序的超链接，或列出多个UID的LinkOut URL和属性。

EGQuery（全局查询）

eutils.ncbi.nlm.nih.gov/enterz/eutils/egquery.fcgi

用每个Entrez数据库中与查询匹配的记录数响应文本查询。

ESpell（拼写建议）

eutils.ncbi.nlm.nih.gov/enterz/eutils/espell.fcgi

检索给定数据库中文本查询的拼写建议。

ECitMatch（PubMed中的批量引用搜索）

eutils.ncbi.nlm.nih.gov/enterz/eutils/ecitmatch.cgi

检索与一组输入引文字符串相对应的PubMed ID（PMID）。

E-utilities Access Entrez数据库

E-utilities访问Entrez系统的核心搜索和检索引擎，因此只能检索Entrez中已有的数据。尽管NCBI的大多数数据都在Entrez中，但仍有几个数据集存在于Entrez系统之外。在使用电子实用程序开始项目之前，请检查是否可以在Entrez数据库中找到所需的数据。

Entrez系统使用UID识别数据库记录

每个Entrez数据库通过称为UID（唯一标识符）的整数ID引用其中的数据记录。UID的示例包括核苷酸和蛋白质的GI编号、PubMed的PMID或结构的MMDB-ID。电子工具将UID用于数据输入和输出，因此，在使用电子工具开始项目之前，了解如何找到与所需数据关联的UID通常是至关重要的，特别是对于高级数据管道而言。

请参见表1以获取Entrez中UID的完整列表。

表1

–选定数据库的Entrez唯一标识符（UID）

使用访问访问序列记录。版本标识符

NCBI现在使用accession.version标识符，而不是GI编号（UID）作为核苷酸和蛋白质序列记录（nuccore、nucest、nugss、popset和蛋白质数据库中的记录）的主要标识符。即便如此，电子实用程序仍继续使用GI编号或附件版本标识符来提供对这些记录的访问。那些接受UID作为输入的E-utilities也将接受accession.version标识符（对于上面列出的序列数据库）。那些输出UID的E-utilities可以输出accession.version标识符，而不是通过将&idtype参数设置为“acc”。最后，EFetch可以检索任何序列记录的accession.version标识符，包括没有GI编号的序列。请参阅第4章有关每个E-utility如何处理accession.version标识符的更多详细信息。

Entrez核心引擎：EGQuery、ESearch和ESummary

Entrez的核心是一个引擎，它为任何Entrez数据库执行两个基本任务：1）组装与文本查询匹配的UID列表，2）检索每个UID的简短摘要记录，称为文档摘要（DocSum）。Entrez引擎的这两个基本任务由ESearch和ESummary执行。ESearch返回与给定Entrez数据库中的文本查询匹配的UID列表，ESummary返回与输入UID列表匹配的DocSums。web Entrez中的文本搜索相当于ESearch-ESummary。EGQuery是ESearch的全局版本，可以同时搜索所有Entrez数据库。因为这三个E-实用程序执行两个核心Entrez功能，所以它们适用于所有Entrez数据库。

egquery.fcgi？术语=查询
esearch.fcgi？数据库=数据库&术语=查询
summary.fcgi？数据库=数据库&标识=uid1、uid2、uid3，。。。

Entrez查询的语法和初始分析

输入到Entrez系统中的文本搜索字符串将转换为以下格式的Entrez查询：

术语1[字段1]操作术语2[字段2]操作术语3[字段3]操作...

其中，这些词是搜索词，每个词都限于方括号中的特定Entrez字段，并使用以下三个布尔运算符之一进行组合：Op=AND、OR或NOT。这些布尔运算符必须全部大写。

示例：人类[生物体]和拓扑异构酶[蛋白质名称]

Entrez最初将查询拆分为一系列最初由查询中的空格分隔的项；因此，空间将每个项和布尔运算符分开是至关重要的。如果查询包含只有对于UID编号（唯一标识符）或登录号的列表，Entrez系统只返回相应的记录，不执行进一步的解析。如果查询包含任何布尔运算符（AND、OR或NOT），则将查询拆分为由这些运算符分隔的术语，然后独立解析每个术语。然后根据布尔运算符组合这些搜索的结果。

有关如何搜索Entrez的完整说明，请参见Entrez帮助文档。有关更多信息，请访问Entrez帮助.

Entrez数据库：EInfo、EFetch和ELink

NCBI Entrez系统目前包含38个数据库。EInfo提供了有关每个数据库的详细信息，包括数据库中索引字段的列表以及到其他Entrez数据库的可用链接。

埃因福.fcgi？数据库=数据库

每个Entrez数据库都包括对原始数据记录的两个主要增强功能：1）用于生成适用于给定数据库的各种显示格式的软件，以及2）指向其他Entrez数据中记录的链接，这些记录显示为相关UID的列表。显示格式功能由EFetch执行，EFetch为输入UID列表生成格式化输出。例如，EFetch可以从Entrez-PubMed或从Entrez Protein生成FASTA格式的摘要。EFetch尚不支持所有Entrez数据库；请参阅EFetch文档详细信息。

efetch.fcgi？db=数据库id=uid1、uid2、uid3&翻新=报告类型&重新调制=
数据模式

链接功能由ELink执行，ELink生成指定Entrez数据库中的UID列表，这些UID链接到同一数据库或另一数据库中的一组输入UID。例如，ELink可以查找与Entrez核苷酸中的记录链接的Entrez SNP记录，或与Entrez-Protein中的记录关联的Entrez-Domain记录。

elink.fcgi？数据库来自=初始数据库数据库=目标数据库&标识=uid1、uid2、uid3

使用Entrez History Server

Entrez系统的一个强大功能是，它可以将检索到的UID集临时存储在服务器上，以便随后将其组合或作为其他E-utility调用的输入提供。Entrez History服务器提供此服务，可以使用Entrez搜索页面上的Preview/Index或History选项卡在Web上进行访问。每个E-utilities还可以使用History服务器，该服务器为每组UID分配一个称为查询键（&query_key）的整数标签和一个名为Web环境（&WebEnv）的编码cookie字符串。EPost允许将任何UID列表上载到历史服务器，并返回查询键和Web环境。ESearch也可以将其输出的一组UID发布到历史服务器，但前提是&usehistory参数设置为“y”。如果&cmd设置为“neighbor_History”，ELink还可以将其输出发布到历史服务器。然后，可以使用EPost或ESearch生成的查询键和Web环境来代替ESummary、EFetch和ELink中的UID列表。

在Entrez中，一组UID在History上由三个参数表示：

&db=数据库&query_key=查询键&WebEnv=web环境

上载生成web环境和查询密钥的步骤

esearch.fcgi？数据库=数据库&术语=查询&usehistory=y

epost.fcgi？数据库=数据库&标识=uid1、uid2、uid3，。。。

elink.fcgi？数据库来自=源数据库（_D）&数据库=目的地db&cmd=邻居历史记录&id=
uid1、uid2，。。。

下载使用web环境和查询键的步骤

summary.fcgi？数据库=数据库&网络环境=韦本夫&查询键=钥匙

efetch.fcgi？数据库=数据库&网络环境=韦本夫&查询键=钥匙&重新打字=
报告类型&重新调制=数据模式

使用web环境和查询键的链接步骤

elink.fcgi？数据库来自=初始数据库数据库=目标数据库&网络环境=
韦本夫&查询键=钥匙

使用web环境和&term参数中的查询键（前面是#，编码为%23）的搜索步骤

esearch.fcgi？数据库=数据库&术语=%23键+AND+查询&网络环境=韦本夫&usehistory=y

在历史服务器上生成多个数据集

历史服务器上的每个web环境都可以与任意数量的查询键相关联。这允许不同的数据集与布尔运算符AND、OR和NOT组合，或与另一个Entrez查询组合。重要的是要记住，要组合两个数据集（查询键），它们必须与同一web环境相关联。默认情况下，连续的E实用程序调用生成的查询键不与相同的web环境关联，因此为了克服此问题，在初始调用后的每个E-utility调用都必须将&WebEnv参数设置为预先存在的web环境的值。

默认行为：这两个URL…

URL 1:epost.fcgi？数据库=数据库&标识=uid1、uid2、uid3
URL 2:esearch.fcgi？数据库=数据库&术语=查询&usehistory=y

将生成与不同web环境关联的两个历史记录集：

URL WebEnv查询键UID
1网站1 uid1，uid2，uid3
2 web2 1 uid匹配查询

期望的行为：这两个URL…

URL 1:epost.fcgi？数据库=数据库&标识=uid1、uid2、uid3
（摘录网站1从URL 1的输出）
网址2:esearch.fcgi？数据库=数据库&术语=查询&使用历史=y&网络环境=网站1

将生成与相同（新）web环境关联的两组：

URL WebEnv查询密钥UID
1网站2 1 uid1，uid2，uid3
2 web2 2 uid匹配查询

基本管道

高级管道