如何调用文本分析 REST API

在本文中,我们将使用文本分析 REST API 和 Postman 来演示这些关键概念。 API 为使用服务的功能提供了若干同步终结点。

创建文本分析资源

使用文本分析 API 之前,需要创建一个 Azure 资源,其中包含应用程序的密钥和终结点。

  1. 首先,转到 Azure 门户并创建一个新的文本分析资源(如果没有)。 选择一个定价层

  2. 选择要用于终结点的区域。

  3. 创建文本分析资源,并转到页面左侧的“密钥和终结点边栏选项卡”。 复制稍后调用 API 时要使用的密钥。 稍后会将此添加为 Ocp-Apim-Subscription-Key 标头的值。

  4. 若要检查使用文本分析资源发送的文本记录数,请执行以下操作:

    1. 导航到 Azure 门户中的文本分析资源。
    2. 单击左侧导航菜单中的“监视”下的“指标” 。
    3. 在“指标”下拉框中选择“已处理的文本记录”。

文本记录是最多包含 1000 个字符的输入文本单位。 例如,作为输入文本提交的 1500 个字符将计为 2 个文本记录。

更改定价层

如果现有文本分析资源使用 S0 到 S4 定价层,则应将其更新为使用标准定价层。 S0 到 S4 定价层将停用。 更新资源定价:

  1. 导航到 Azure 门户中的文本分析资源。
  2. 选择左侧导航菜单中的“定价层”。 它将在“资源管理”下。
  3. 选择标准 (S) 定价层。 然后单击“选择”。

你还可以使用标准 (S) 定价层创建新的文本分析资源,并迁移应用程序以使用新资源凭据。

同步使用 API

你可以同步调用文本分析(用于低延迟方案)。 使用同步 API 时,必须单独调用每个 API(功能)。 如果需要调用多个功能,请查看以下部分,了解如何以异步方式调用文本分析。

API 请求格式

可以同时将两个同步调用发送到文本分析 API。

同步请求

对于所有同步操作,API 请求的格式都是相同的。 文档作为原始非结构化文本提交到 JSON 对象。 不支持 XML。 JSON 架构由下面描述的元素组成。

元素 有效值 必需? 使用情况
id 数据类型为字符串,但实际上文档 ID 往往是整数。 必选 系统使用你提供的 ID 来构建输出。 为请求中的每个 ID 生成语言代码、关键短语和情绪分数。
text 非结构化原始文本,最多 5,120 个字符。 必选 对于语言检测,可以使用任何语言来表示文本。 对于情绪分析、关键短语提取和实体标识,此文本必须使用支持的语言
language 支持语言的 2 字符 ISO 639-1 代码 多种多样 需要情绪分析、关键短语提取、实体链接;语言检测为可选。 排除语言检测不会有任何错误,但没有它会削弱分析。 语言代码应对应你提供的 text

下面是同步文本分析终结点的 API 请求示例。

{
  "documents": [
    {
      "language": "en",
      "id": "1",
      "text": "Sample text to be sent to the text analytics api."
    }
  ]
}

提示

有关将数据发送到文本分析 API 的速率和大小限制的信息,请参阅数据和速率限制一文。

设置请求

在 Postman(或其他 Web API 测试工具)中,为要使用的功能添加终结点。 使用下表查找适当的终结点格式,并将 <your-text-analytics-resource> 替换为资源终结点。 例如:

https://my-resource.cognitiveservices.azure.cn/text/analytics/v3.0/languages

用于发送同步请求的终结点

功能 请求类型 资源终结点
语言检测 POST <your-text-analytics-resource>/text/analytics/v3.0/languages
情绪分析 POST <your-text-analytics-resource>/text/analytics/v3.0/sentiment
观点挖掘 POST <your-text-analytics-resource>/text/analytics/v3.1-preview.5/sentiment?opinionMining=true
关键短语提取 POST <your-text-analytics-resource>/text/analytics/v3.0/keyPhrases
命名实体识别 - 常规 POST <your-text-analytics-resource>/text/analytics/v3.0/entities/recognition/general
命名实体识别 - PII POST <your-text-analytics-resource>/text/analytics/v3.1-preview.5/entities/recognition/pii
实体链接 POST <your-text-analytics-resource>/text/analytics/v3.0/entities/linking

获得终结点后,在 Postman(或其他 Web API 测试工具)中执行以下操作:

  1. 选择要使用的功能的请求类型。

  2. 从上表中粘贴所需的正确操作的终结点。

  3. 设置三个请求标头:

    • Ocp-Apim-Subscription-Key:从 Azure 门户获得的访问密钥
    • Content-Type:application/json
    • Accept:application/json

    如果使用的是 Postman,则请求应类似于以下屏幕截图(假设有一个 /keyPhrases 终结点)。

    请求带终结点和标头的屏幕截图

  4. 为“正文”选择“原始”格式

    请求具有正文设置的屏幕截图

  5. 以有效格式粘贴一些 JSON 文档。 使用上面“API 请求格式”部分中的示例,有关详细信息和示例,请参阅以下主题:

发送请求

提交 API 请求。 如果调用了同步终结点,则响应将立即显示为一个 JSON 文档,其中包含请求中提供的每个文档 ID 的项。

示例 API 响应

同步操作的示例响应

同步终结点响应将根据你使用的终结点而有所不同。 有关示例响应,请参阅以下文章。

另请参阅