Natural Language API 基础知识

本文档介绍了使用 Cloud Natural Language API 的基础知识。 本概念指南说明了您可以对 Natural Language API 发出的请求类型、如何构建这些请求以及如何处理其响应。我们建议 Natural Language API 的所有用户先阅读本指南和某一关联教程，然后再深入研究 API 本身。

Natural Language 的功能

Natural Language API 有几种方法可以对文本进行分析和注释。每个级别的分析都为语言理解提供有价值的信息。下面列出了这些方法：

• 情感分析检测给定文本，并确定文本中的主导性情绪观点，尤其是确定作者的态度是积极、消极还是中立的。情感分析是通过 analyzeSentiment 方法执行的。

• 实体分析检测给定文本以找出已知实体（公众人物、地标等专有名词，以及餐厅、体育场等普通名词），并返回这些实体的相关信息。实体分析是通过 analyzeEntities 方法执行的。

• 实体情感分析检测给定文本以找出已知实体（专有名词和普通名词），并返回这些实体的相关信息，同时确定对文本中实体的主导性情绪观点，尤其是确定作者对实体的态度是积极、消极还是中立的。 实体分析是通过 analyzeEntitySentiment 方法执行的。

• 语法分析提取语言信息，将给定文本分解为一系列句子和词条词法单元（通常是字词边界），从而对这些词法单元进行进一步分析。语法分析是通过 analyzeSyntax 方法执行的。

• 内容分类分析文本内容并返回内容所属的内容类别。内容分类是通过 classifyText 方法执行的。

如果调用方未在初始请求中指定语言，则每个 API 调用还会检测并返回语言。

此外，如果您希望仅使用一次 API 调用对给定文本执行多项自然语言操作，还可以使用 annotateText 请求执行情感分析和实体分析。

Natural Language API 基本请求

Natural Language API 是一个 REST API，由 JSON 请求和响应组成。下面显示一个简单的 Natural Language JSON 实体分析请求：

{
  "document":{
    "type":"PLAIN_TEXT",
    "language_code": "EN",
    "content":"'Lawrence of Arabia' is a highly rated film biography about
                British Lieutenant T. E. Lawrence. Peter O'Toole plays
                Lawrence in the film."
  },
  "encodingType":"UTF8"
}

这些字段的含义如下：

• document 包含此请求的数据，其中包含以下子字段：
  • type - 文档类型（HTML 或 PLAIN_TEXT）
  • language-（可选）请求中文本的语言。如果未指定，系统将自动检测语言。有关 Natural Language API 支持哪些语言的信息，请参阅语言支持。不支持的语言将在 JSON 响应中返回错误。
    
  • content 或 gcsContentUri，其中包含待评估的文本。 如果传递 content，则该文本直接包含在 JSON 请求中（如上所示）。如果传递 gcsContentUri，则该字段必须包含 URI，指向 Google Cloud Storage 中的文本内容。
• 编码类型 -（必填）计算返回的字符在文本中的偏移所采用的编码方案，必须与传递的文本的编码匹配。 如果未设置此参数，请求将不会出错，但所有这些偏移都将设置为 -1。

指定文本内容

传递 Natural Language API 请求时，您可以通过以下两种方式中的一种指定要处理的文本：

• 直接在 content 字段中传递文本。
• 在 gcsContentUri 字段中传递 Google Cloud Storage URI。

无论哪种情况，您都应该确保传递的内容不超过内容限制允许的范围。请注意，这些内容限制是按字节而不是字符计算的；因此字符长度取决于文本的编码。

以下请求引用一个包含葛底斯堡演说的 Google Cloud Storage 文件：

{
  "document":{
    "type":"PLAIN_TEXT",
    "language": "EN",
    "gcsContentUri":"gs://cloud-samples-tests/natural-language/gettysburg.txt"
  },
}

情感分析

情感分析尝试确定文本中传达的整体态度（积极或消极）。情感由数值 score 和 magnitude 表示。

情感分析响应字段

下面是葛底斯堡演说的 analyzeSentiment 响应的一个示例：

{
  "documentSentiment": {
    "score": 0.2,
    "magnitude": 3.6
  },
  "language_code": "en",
   "sentences": [
    {