如何调用文本分析 REST APIHow to call the Text Analytics REST API

在本文中,我们将使用文本分析 REST API 和 Postman 来演示这些关键概念。In this article, we use the Text Analytics REST API and Postman to demonstrate key concepts. API 为使用服务的功能提供了若干同步终结点。The API provides several synchronous endpoints for using the features of the service.

创建文本分析资源Create a Text Analytics resource

使用文本分析 API 之前,需要创建一个 Azure 资源,其中包含应用程序的密钥和终结点。Before you use the Text Analytics API, you will need to create a Azure resource with a key and endpoint for your applications.

  1. 首先,转到 Azure 门户并创建一个新的文本分析资源(如果没有)。First, go to the Azure portal and create a new Text Analytics resource, if you don't have one already. 选择一个定价层Choose a pricing tier.

  2. 选择要用于终结点的区域。Select the region you want to use for your endpoint.

  3. 创建文本分析资源,并转到页面左侧的“密钥和终结点边栏选项卡”。Create the Text Analytics resource and go to the “keys and endpoint blade” in the left of the page. 复制稍后调用 API 时要使用的密钥。Copy the key to be used later when you call the APIs. 稍后会将此添加为 Ocp-Apim-Subscription-Key 标头的值。You'll add this later as a value for the Ocp-Apim-Subscription-Key header.

更改定价层Change your pricing tier

如果现有文本分析资源使用 S0 到 S4 定价层,则应将其更新为使用标准定价层If you have an existing Text Analytics resource using the S0 through S4 pricing tier, you should update it to use the Standard (S) pricing tier. S0 到 S4 定价层将停用。The S0 through S4 pricing tiers will be retired. 更新资源定价:To update your resource's pricing:

  1. 导航到 Azure 门户中的文本分析资源。Navigate to your Text Analytics resource in the Azure portal.
  2. 选择左侧导航菜单中的“定价层”。Select Pricing tier in the left navigation menu. 它将在“资源管理”下。It will be below RESOURCE MANAGEMENT.
  3. 选择标准 (S) 定价层。Choose the Standard (S) pricing tier. 然后单击“选择”。Then click Select.

你还可以使用标准 (S) 定价层创建新的文本分析资源,并迁移应用程序以使用新资源凭据。You can also create a new Text Analytics resource with the Standard (S) pricing tier, and migrate your applications to use the credentials for the new resource.

同步使用 APIUsing the API synchronously

你可以同步调用文本分析(用于低延迟方案)。You can call Text Analytics synchronously (for low latency scenarios). 使用同步 API 时,必须单独调用每个 API(功能)。You have to call each API (feature) separately when using synchronous API. 如果需要调用多个功能,请查看以下部分,了解如何以异步方式调用文本分析。If you need to call multiple features then check out below section on how to call Text Analytics asynchronously.

API 请求格式API request formats

可以同时将两个同步调用发送到文本分析 API。You can send both synchronous calls to the Text Analytics API.

同步请求Synchronous requests

对于所有同步操作,API 请求的格式都是相同的。The format for API requests is the same for all synchronous operations. 文档作为原始非结构化文本提交到 JSON 对象。Documents are submitted in a JSON object as raw unstructured text. 不支持 XML。XML is not supported. JSON 架构由下面描述的元素组成。The JSON schema consists of the elements described below.

元素Element 有效值Valid values 必需?Required? 使用情况Usage
id 数据类型为字符串,但实际上文档 ID 往往是整数。The data type is string, but in practice document IDs tend to be integers. 必选Required 系统使用你提供的 ID 来构建输出。The system uses the IDs you provide to structure the output. 为请求中的每个 ID 生成语言代码、关键短语和情绪分数。Language codes, key phrases, and sentiment scores are generated for each ID in the request.
text 非结构化原始文本,最多 5,120 个字符。Unstructured raw text, up to 5,120 characters. 必选Required 对于语言检测,可以使用任何语言来表示文本。For language detection, text can be expressed in any language. 对于情绪分析、关键短语提取和实体标识,此文本必须使用支持的语言For sentiment analysis, key phrase extraction and entity identification, the text must be in a supported language.
language 支持语言的 2 字符 ISO 639-1 代码2-character ISO 639-1 code for a supported language 多种多样Varies 需要情绪分析、关键短语提取、实体链接;语言检测为可选。Required for sentiment analysis, key phrase extraction, and entity linking; optional for language detection. 排除语言检测不会有任何错误,但没有它会削弱分析。There is no error if you exclude it, but the analysis is weakened without it. 语言代码应对应你提供的 textThe language code should correspond to the text you provide.

下面是同步文本分析终结点的 API 请求示例。The following is an example of an API request for the synchronous Text Analytics endpoints.

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

提示

有关将数据发送到文本分析 API 的速率和大小限制的信息,请参阅数据和速率限制一文。See the Data and rate limits article for information on the rates and size limits for sending data to the Text Analytics API.

设置请求Set up a request

在 Postman(或其他 Web API 测试工具)中,为要使用的功能添加终结点。In Postman (or another web API test tool), add the endpoint for the feature you want to use. 使用下表查找适当的终结点格式,并将 <your-text-analytics-resource> 替换为资源终结点。Use the table below to find the appropriate endpoint format, and replace <your-text-analytics-resource> with your resource endpoint. 例如:For example:

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

用于发送同步请求的终结点Endpoints for sending synchronous requests

功能Feature 请求类型Request type 资源终结点Resource endpoints
语言检测Language detection POSTPOST <your-text-analytics-resource>/text/analytics/v3.0/languages
情绪分析Sentiment analysis POSTPOST <your-text-analytics-resource>/text/analytics/v3.0/sentiment
观点挖掘Opinion Mining POSTPOST <your-text-analytics-resource>/text/analytics/v3.0/sentiment?opinionMining=true
关键短语提取Key phrase extraction POSTPOST <your-text-analytics-resource>/text/analytics/v3.0/keyPhrases
命名实体识别 - 常规Named entity recognition - general POSTPOST <your-text-analytics-resource>/text/analytics/v3.0/entities/recognition/general

获得终结点后,在 Postman(或其他 Web API 测试工具)中执行以下操作:After you have your endpoint, in Postman (or another web API test tool):

  1. 选择要使用的功能的请求类型。Choose the request type for the feature you want to use.

  2. 从上表中粘贴所需的正确操作的终结点。Paste in the endpoint of the proper operation you want from the above table.

  3. 设置三个请求标头:Set the three request headers:

    • Ocp-Apim-Subscription-Key:从 Azure 门户获得的访问密钥Ocp-Apim-Subscription-Key: your access key, obtained from Azure portal
    • Content-Type:application/jsonContent-Type: application/json
    • Accept:application/jsonAccept: application/json

    如果使用的是 Postman,则请求应类似于以下屏幕截图(假设有一个 /keyPhrases 终结点)。If you're using Postman, your request should look similar to the following screenshot, assuming a /keyPhrases endpoint.

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

  4. 为“正文”选择“原始”格式Choose raw for the format of the Body

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

  5. 以有效格式粘贴一些 JSON 文档。Paste in some JSON documents in a valid format. 使用上面“API 请求格式”部分中的示例,有关详细信息和示例,请参阅以下主题:Use the examples in the API request format section above, and for more information and examples, see the topics below:

发送请求Send the request

提交 API 请求。Submit the API request. 如果调用了同步终结点,则响应将立即显示为一个 JSON 文档,其中包含请求中提供的每个文档 ID 的项。If you made the call to a synchronous endpoint, the response will be displayed immediately, as a single JSON document, with an item for each document ID provided in the request.

示例 API 响应Example API responses

同步操作的示例响应Example responses for synchronous operation

同步终结点响应将根据你使用的终结点而有所不同。The synchronous endpoint responses will vary depending on the endpoint you use. 有关示例响应,请参阅以下文章。See the following articles for example responses.

另请参阅See also