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

对文本分析 API 的调用为 HTTP POST/GET 调用,可以用任何语言表示。Calls to the Text Analytics API are HTTP POST/GET calls, which you can formulate in any language. 在本文中,我们将使用 REST 和 Postman 来演示这些关键概念。In this article, we use REST and Postman to demonstrate key concepts.

每个请求必须包括访问密钥和 HTTP 终结点。Each request must include your access key and an HTTP endpoint. 终结点指定你在注册期间选择的区域、服务 URL 和在请求上使用的资源:sentimentkeyphraseslanguagesentitiesThe endpoint specifies the region you chose during sign up, the service URL, and a resource used on the request: sentiment, keyphrases, languages, and entities.

回想一下,文本分析是无状态的,因此,没有任何要管理的数据资产。Recall that Text Analytics is stateless so there are no data assets to manage. 收到文本后将对其进行上传和分析,其结果会立即返回到调用应用程序。Your text is uploaded, analyzed upon receipt, and results are returned immediately to the calling application.

先决条件Prerequisites

必须拥有可以访问文本分析 API 的认知服务 API 订阅You must have a Cognitive Services API subscription with access to the Text Analytics API. 如果没有订阅,可以创建一个 1 元试用帐户If you don't have a subscription, you can create a 1rmb trial account. 在继续操作之前,需使用激活帐户后由系统提供的文本分析订阅密钥。Before continuing, you will need the Text Analytics subscription key provided after activating your account.

JSON 架构定义JSON schema definition

输入必须是原始非结构化文本的 JSON。Input must be JSON in raw unstructured text. 不支持 XML。XML is not supported. 架构十分简单,包括以下列表中描述的元素。The schema is simple, consisting of the elements described in the following list.

当前可以提交所有文本分析操作的相同文档:情绪、关键短语、语言检测和实体标识。You can currently submit the same documents for all Text Analytics operations: sentiment, key phrase, language detection, and entity identification. (每个分析的架构在未来可能会有所变化。)(The schema is likely to vary for each analysis in the future.)

元素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.

有关限制的详细信息,请参阅文本分析概述 > 数据限制For more information about limits, see Text Analytics Overview > Data limits.

在 Postman 中设置请求Set up a request in Postman

该服务接受最大 1 MB 的请求。The service accepts request up to 1 MB in size. 如果使用 Postman(或另一个 Web API 测试工具),则设置终结点来包含要使用的资源,并在请求标头中提供访问密钥。If you are using Postman (or another Web API test tool), set up the endpoint to include the resource you want to use, and provide the access key in a request header. 每个操作均要求将适当的资源追加到终结点。Each operation requires that you append the appropriate resource to the endpoint.

  1. 在 Postman 中:In Postman:

    • 选择“Post” 作为请求类型。Choose Post as the request type.
    • 粘贴从门户页中复制的终结点。Paste in the endpoint you copied from the portal page.
    • 附加资源。Append a resource.

    资源终结点如下所示(你的区域可能有所不同):Resource endpoints are as follows (your region may vary):

    • https://chinaeast2.api.cognitive.azure.cn/text/analytics/v2.1/sentiment
    • https://chinaeast2.api.cognitive.azure.cn/text/analytics/v2.1/keyPhrases
    • https://chinaeast2.api.cognitive.azure.cn/text/analytics/v2.1/languages
    • https://chinaeast2.api.cognitive.azure.cn/text/analytics/v2.1/entities
  2. 设置三个请求标头:Set the three request headers:

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

    请求应类似于以下屏幕截图,假设 /keyPhrases 资源。Your request should look similar to the following screenshot, assuming a /keyPhrases resource.

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

  3. 单击“正文” ,然后选择“原始” 格式。Click Body and choose raw for the format.

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

  4. 采用对预期分析有效的格式粘贴某些 JSON 文档。Paste in some JSON documents in a format that is valid for the intended analysis. 有关特定分析的详细信息,请参阅下面的主题:For more information about a particular analysis, see the topics below:

  1. 单击“发送” 以提交请求。Click Send to submit the request. 有关每分钟和每秒可以发送的请求数的信息,请参阅概述中的数据限制部分。See the data limits section in the overview for information on the number of requests you can send per minute and second.

    在 Postman 中,响应会在下一个窗口中显示为单个 JSON 文档,请求中提供的每个文档 ID 对应一个条目。In Postman, the response is displayed in the next window down, as a single JSON document, with an item for each document ID provided in the request.

另请参阅See also

文本分析概述Text Analytics Overview
常见问题解答 (FAQ)Frequently asked questions (FAQ)

后续步骤Next steps