本文提供 Cloud Natural Language API 的基本使用指南。這份概念指南涵蓋了您可以向 Natural Language API 提出的要求類型、如何建構這些要求，以及如何處理其回應等資訊。我們建議 Natural Language API 的所有使用者，先閱讀這份指南並完成一個相關聯的教學課程後，再去深入瞭解 API 本身。
Natural Language 功能
Natural Language API 提供多種可讓您執行文字分析與註解的方法。各個分析步驟都為理解語言提供了寶貴的資訊。以下列出這些方法：
情緒分析會檢查指定的文字內容，進而識別文字內容的主要情緒主張，特別是判斷撰寫者的態度為正面、負面或中立。情緒分析是透過
analyzeSentiment方法執行。實體分析會檢查指定文字中的已知實體 (公眾人物、等專有名詞；餐廳或體育館等普通名詞) 並傳回有關這些實體的資訊。實體分析是透過
analyzeEntities方法執行。實體情緒分析會檢查指定文字中的已知實體 (專有名詞和普通名詞)，傳回這些實體的相關資訊，並識別文字中實體的主要情緒主張，特別是判斷撰寫者對實體的態度為正面、負面或中立。實體分析是透過
analyzeEntitySentiment方法執行。語法分析會擷取語言資訊，將指定的文字內容拆解為各段語句與符記 (通稱斷詞) 並提供有關這些符記的進一步分析。語法分析是透過
analyzeSyntax方法執行。內容分類會分析文字內容並傳回其內容類別。內容分類是透過
classifyText方法執行。
若進行 API 呼叫者未在初始要求中指定語言，所有 API 呼叫會偵測並傳回該語言的資訊。
此外，如果您想使用單一 API 呼叫，對指定文字執行多項自然語言作業，也可以使用 annotateText 要求執行情緒分析和實體分析。
基本的 Natural Language 要求
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，且此 URI 須指向 Google Cloud Storage 中的文字內容。
- encodingType - (必填) 計算傳回的字元在文字內容中的位移值時採用的編碼配置，該編碼配置必須符合傳遞文字的編碼。如未設定此參數，要求雖不會發生錯誤，但會將這些位移值都設為
-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": [ { "text": { "content": "Four score and seven years ago our fathers brought forth on this continent a new nation, conceived in liberty and dedicated to the proposition that all men are created equal.", "beginOffset": 0 }, "sentiment": { "magnitude": 0.8, "score": 0.8 } }, ... }
這些欄位值的說明如下：
documentSentiment提供文件的整體情緒，由下列欄位組成：- 情緒的
score範圍介於-1.0(負面) 和1.0(正面) 之間，可反映文字的整體情緒傾向。 magnitude表示指定文字的整體情緒強度 (包括正面和負面)，介於0.0和+inf之間。與score不同的是，magnitude並無正規化；文字內容中的每種情緒表達 (無論正負面) 都會提高文字的magnitude值 (因此文字篇幅較長，幅度值可能也會較大)。documentSentiment
- 情緒的
language_code提供文件的語言資訊，可在初始要求中傳遞，亦可由系統自動偵測 (如果沒有的話)。language_supported包含布林值，用於識別語言是否為官方支援的語言sentences提供從原始文件中擷取的語句清單，其中包含：sentiment提供各個語句的「語句整體情緒」值，包含介於-1.0(負面) 和1.0(正面) 之間的score，以及介於0.0和1.0之間的magnitude值。請注意，magnitude會針對sentences正規化。
蓋茨堡宣言的情緒值為 0.2，代表情緒偏向正面，magnitude 值為 3.6，代表在文件篇幅不長 (約一個段落) 的前提下，文件情緒相對強烈。請注意，蓋茨堡演說的第一句含有非常高的正面 score，即 0.8。
情緒分析值說明
文件的情緒分數 (score) 代表文件的整體情緒。文件情緒的 magnitude 值表示文件中情緒內容的程度，通常與文件長度成正比。
值得注意的是，Natural Language API 可區分文件中的正面與負面情緒，但無法辨識確切的正面與負面情緒。舉例來說，「生氣」和「難過」都是負面情緒。然而，當 Natural Language API 分析視為「生氣」或「難過」的文字時，僅會在回應中表示文字為負面情緒，而非「生氣」或「難過」。
如果文件的情緒分數接近 0.0，可能代表文件情緒較為平淡，也可能代表文件同時含有強烈的正面和負面情緒，兩者相互抵銷。一般而言，您可以透過 magnitude 值來消除這些情況的歧義，因為真正中立的文件會有較低的 magnitude 值，而混合文件則會有較高的量值。
比較文件時 (尤其是長度不同的文件)，請務必使用 magnitude 值校正分數，因為這有助於評估相關的情緒內容量。
下方圖表顯示部分範例值並說明如何解讀：
| 情緒 | 範例值 |
|---|---|
| 明顯正面* | "score"：0.8，"magnitude"：3.0 |
| 明顯負面* | "score"：-0.6，"magnitude"：4.0 |
| 普通 | "score"：0.1，"magnitude"：0.0 |
| 混合 | "score"：0.0，"magnitude"：4.0 |
* 「明顯正面」和「明顯負面」的情緒會因為用途和客戶而有所不同。您可能會在自己的情境中得到不同的結果。建議您定義適合自身情況的臨界值，並在測試與驗證結果後調整這個臨界值。舉例來說，您可能會將任何超過 0.25 分數臨界值的分數定義為明顯正面，然後在檢閱您的資料與結果後，發現分數 0.15 至 0.25 也應視為正面，因而將分數臨界值修改為 0.15。
實體分析
實體分析提供文字中有關實體的資訊，通常是指具有名稱的「事物」，例如名人、地標或一般物體等。
實體大致可分為兩種類別：對應至唯一實體 (特定人名或地名等) 的專有名詞或是普通名詞 (在自然語言處理中亦稱為「一般名詞」)。常用的認定標準是，只要是名詞就可視為「實體」。實體會依照原文傳回索引位移值。
實體分析要求應傳遞 encodingType 引數，如此才可正確解譯傳回的位移值。
實體分析回應欄位
實體分析會傳回一組偵測到的實體，以及與這些實體相關聯的參數，例如實體類型、實體與整體文字的關聯性，以及文字中參照相同實體的位置。
以下為實體要求的 analyzeEntities 回應：
{ "entities": [ { "name": "British", "type": "LOCATION", "metadata": {}, "mentions": [ { "text": { "content": "British", "beginOffset": 58 }, "type": "PROPER", "probability": 0.941 } ] }, { "name": "Lawrence", "type": "PERSON", "metadata": {}, "mentions": [ { "text": { "content": "Lawrence", "beginOffset": 113 }, "type": "PROPER", "probability": 0.914 } ] }, { "name": "Lawrence of Arabia", "type": "WORK_OF_ART", "metadata": {}, "mentions": [ { "text": { "content": "Lawrence of Arabia", "beginOffset": 0 }, "type": "PROPER", "probability": 0.761 } ] }, { "name": "Lieutenant", "type": "PERSON", "metadata": {}, "mentions": [ { "text": { "content": "Lieutenant", "beginOffset": 66 }, "type": "COMMON", "probability": 0.927 } ] }, { "name": "Peter O Toole", "type": "PERSON", "metadata": {}, "mentions": [ { "text": { "content": "Peter O Toole", "beginOffset": 93 }, "type": "PROPER", "probability": 0.907 } ] }, { "name": "T. E. Lawrence", "type": "PERSON", "metadata": {}, "mentions": [ { "text": { "content": "T. E. Lawrence", "beginOffset": 77 }, "type": "PROPER", "probability": 0.853 } ] }, { "name": "film", "type": "WORK_OF_ART", "metadata": {}, "mentions": [ { "text": { "content": "film", "beginOffset": 129 }, "type": "COMMON", "probability": 0.805 } ] }, { "name": "film biography", "type": "WORK_OF_ART", "metadata": {}, "mentions": [ { "text": { "content": "film biography", "beginOffset": 37 }, "type": "COMMON", "probability": 0.876 } ] } ], "languageCode": "en", "languageSupported": true }
請注意，Natural Language API 同時傳回《Lawrence of Arabia》(電影) 以及「T.E. Lawrence」(人物) 的實體。實體分析能夠區分相似的實體，例如此案例中的「Lawrence」。
用於儲存實體參數的欄位所列如下：
type代表實體類型 (例如這個實體為人物、地點或消費性商品等)。這項資訊有助區分及/或釐清不同的實體，適合用於撰寫模式或擷取資訊。舉例來說，type值有助區分名稱相近的實體，例如區分標記為WORK_OF_ART(電影) 的《Lawrence of Arabia》以及標記為PERSON的「T.E. Lawrence」。(詳情請參閱實體類型。)metadata提供實體在知識存放庫的來源資訊。更多存放庫可能會在往後陸續推出。mentions代表實體在文字內容中被提及時的位移位置。如果您要尋找「Lawrence」這個人名 (而非電影名) 在文字內容中被提及的所有位置，這項資訊將可派上用場。您也可以使用 mentions 來收集實體的別名清單，例如「Lawrence」跟「T.E. Lawrence」都是用來指相同的實體。實體提及類型有兩種：PROPER或COMMON。舉例來說，實體「Lawrence of Arabia」可能直接以專有名詞的形式做為電影片名出現，或以 T.E. Lawrence 的「電影傳記」之類的普通名詞形式出現。
實體情緒分析
實體情緒分析結合了實體分析和情緒分析，並嘗試判斷文字中針對實體表達的情緒 (正面或負面)。實體情緒以數值分數和強度值表示，並針對每次提及實體時決定。這些分數會匯總為實體的整體情緒分數與幅度。
實體情緒分析要求
您可以透過下列格式使用 analyzeEntitySentiment 方法，將實體情緒分析要求傳送至 Natural Language API：
{ "document":{ "type":"PLAIN_TEXT", "content":"I love R&B music. Marvin Gaye is the best. 'What's Going On' is one of my favorite songs. It was so sad when Marvin Gaye died." }, "encodingType":"UTF8" }
您可以在要求中指定選用的 language 參數，識別 content 參數中文字的語言代碼。如果您沒有指定 language 參數，Natural Language API 會自動偵測要求內容的語言。如需有關 Natural Language API 支援哪些語言的資訊，請參閱語言支援。
實體情緒分析回應
Natural Language API 會處理指定文字來擷取實體並判斷情緒。實體情緒分析要求會傳回包含在文件內容中找到的 entities、實體每次提及時的 mentions 項目，以及每次提及時的數值 score 和 magnitude 值 (如「解讀情緒分析值」一文所述)。實體的整體 score 和 magnitude 值是每次提及實體時各自 score 和 magnitude 值的匯總。如果文字中的情緒偏向負面，導致 magnitude 為 0，或是情緒複雜導致 score 為 0，實體的 score 和 magnitude 值可能為 0。
{ "entities": [ { "name": "R&B music", "type": "WORK_OF_ART", "metadata": {}, "salience": 0.5306305, "mentions": [ { "text": { "content": "R&B music", "beginOffset": 7 }, "type": "COMMON", "sentiment": { "magnitude": 0.9, "score": 0.9 } } ], "sentiment": { "magnitude": 0.9, "score": 0.9 } }, { "name": "Marvin Gaye", "type": "PERSON", "metadata": { "mid": "/m/012z8_", "wikipedia_url": "http://en.wikipedia.org/wiki/Marvin_Gaye" }, "salience": 0.21584158, "mentions": [ { "text": { "content": "Marvin Gaye", "beginOffset": 18 }, "type": "PROPER", "sentiment": { "magnitude": 0.4, "score": 0.4 } }, { "text": { "content": "Marvin Gaye", "beginOffset": 138 }, "type": "PROPER", "sentiment": { "magnitude": 0.2, "score": -0.2 } } ], "sentiment": { "magnitude": 0.6, "score": 0.1 } }, ... ], "language": "en" }
範例請見分析實體情緒。
語法分析
Natural Language API 的語法分析功能提供多種強大的文字分析與剖析工具。如要執行語法分析，請使用 analyzeSyntax 方法。
語法分析包含下列作業：
- 語句擷取會將一段文字拆解為一連串語句。
- 斷詞會將一段文字拆解為一連串詞元，一個詞元通常會對應至一個字詞。
- Natural Language API 接著會處理符記，根據符記在語句中的位置為其加入語法資訊。
如需語法符記的完整說明，請參閱構詞學與相依樹狀結構指南。
語法分析要求
您可以透過下列格式使用 analyzeSyntax 方法，將語法分析要求傳送至 Natural Language API：
{ "document":{ "type":"PLAIN_TEXT", "content":"Ask not what your country can do for you, ask what you can do for your country." }, "encodingType":"UTF8" }
語法分析回應
Natural Language API 會處理指定文字來擷取語句和符記。語法分析要求會傳回包含下列 sentences 和 tokens 的回應：
{ "sentences": [ ... Array of sentences with sentence information ], "tokens": [ ... Array of tokens with token information ] }
語句擷取
執行語法分析時，Natural Language API 會傳回一連串從指定文字中擷取的語句，且各個語句在 text 父項中會包含下列欄位：
beginOffset表示語句的開始位置在指定文字中的字元位移值 (從零算起)。請注意，位移值是使用傳遞的encodingType來計算得出。content包含擷取語句的完整文字。
舉例來說，蓋茨堡宣言的語法分析要求會傳回下列 sentences 元素：
{ "sentences": [ { "text": { "content": "Four score and seven years ago our fathers brought forth on this continent a new nation, conceived in liberty and dedicated to the proposition that all men are created equal.", "beginOffset": 0 } }, { "text": { "content": "Now we are engaged in a great civil war, testing whether that nation or any nation so conceived and so dedicated can long endure.", "beginOffset": 175 } }, ... ... { "text": { "content": "It is rather for us to be here dedicated to the great task remaining before us--that from these honored dead we take increased devotion to that cause for which they gave the last full measure of devotion--that we here highly resolve that these dead shall not have died in vain, that this nation under God shall have a new birth of freedom, and that government of the people, by the people, for the people shall not perish from the earth.", "beginOffset": 1002 } } ], "language": "en" }
Natural Language API 的語法分析要求還會提供一連串符記。您可以利用各符記的關聯資訊，對傳回的語句執行進一步的分析。如需這些符記的詳細資訊，請參閱構詞學與相依樹狀結構指南。
代碼化
analyzeSyntax 方法也會將文字轉換為一系列符記，對應至所傳內容的不同文字元素 (字詞邊界)。Natural Language API 開發這組符記的過程稱為「符記化」。
擷取這些符記後，Natural Language API 會處理這些符記來判定與其相關聯的詞性 (包括構詞學資訊) 與詞條。此外，您能夠評估符記在相依樹狀結構中的位置來判定符記的語法意義，並說明符記彼此之間及符記與母句之間的關係。與這些符記相關聯的語法學跟構詞學資訊可用於在 Natural Language API 中瞭解語句的語法結構。
語法分析 JSON 回應傳回的符記欄位如下所示：
text包含與這個符記相關聯的文字資料，具有下列子欄位：beginOffset提供在指定文字中的字元位移值 (從零算起)。請注意，雖然符記是表達在語句中的從屬關係 (說明如下)，但符記位移值是以符記在整段文字的位置來計算。請注意，位移值是使用傳遞的encodingType來計算得出。content提供原文的實際文字內容。
partOfSpeech提供文法資訊，包括符記的構詞學資訊，例如符記的時態、人稱、單複數、性別等 (如需更多有關這些欄位的完整資訊，請參閱構詞學與相依樹狀結構指南)。lemma包含字詞的基礎「根本」，能夠讓您在文字中透過標準化方式使用文字。舉例來說，「write」、「writing」、「wrote」和「written」都是以相同的詞條 (「write」) 為基礎。同樣地，單複數也都是從詞條衍生而來：「house」和「houses」兩者的原形相同。(請參閱「詞條 (構詞學)」一文。)dependencyEdge欄位可透過直接樹狀結構的界線識別符記母句中字詞之間的關係。這項資訊在翻譯、資訊擷取及摘要時相當實用。(構詞學與相依樹狀結構指南提供更多關於從屬剖析的詳細資料。)每個dependencyEdge欄位都會包含下列子欄位：headTokenIndex提供這個符記的「父項符記」在符記母句中的索引值 (從零算起)。不具父項的符記會索引至自己。label提供這個符記對其中心語符記的從屬類別資訊。
下列引述自羅斯福總統就職演說的文字將會產生下列符記：
注意：為求明確，含有 *_UNKNOWN 值的所有 partOfSpeech 標記都已移除。
"tokens": [ { "text": { "content": "The", "beginOffset": 4 }, "partOfSpeech": { "tag": "DET", }, "dependencyEdge": { "headTokenIndex": 2, "label": "DET" }, "lemma": "The" }, { "text": { "content": "only", "beginOffset": 8 }, "partOfSpeech": { "tag": "ADJ", }, "dependencyEdge": { "headTokenIndex": 2, "label": "AMOD" }, "lemma": "only" }, { "text": { "content": "thing", "beginOffset": 13 }, "partOfSpeech": { "tag": "NOUN", "number": "SINGULAR", }, "dependencyEdge": { "headTokenIndex": 7, "label": "NSUBJ" }, "lemma": "thing" }, { "text": { "content": "we", "beginOffset": 19 }, "partOfSpeech": { "tag": "PRON", "case": "NOMINATIVE", "number": "PLURAL", "person": "FIRST", }, "dependencyEdge": { "headTokenIndex": 4, "label": "NSUBJ" }, "lemma": "we" }, { "text": { "content": "have", "beginOffset": 22 }, "partOfSpeech": { "tag": "VERB", "mood": "INDICATIVE", "tense": "PRESENT", }, "dependencyEdge": { "headTokenIndex": 2, "label": "RCMOD" }, "lemma": "have" }, { "text": { "content": "to", "beginOffset": 27 }, "partOfSpeech": { "tag": "PRT", }, "dependencyEdge": { "headTokenIndex": 6, "label": "AUX" }, "lemma": "to" }, { "text": { "content": "fear", "beginOffset": 30 }, "partOfSpeech": { "tag": "VERB", }, "dependencyEdge": { "headTokenIndex": 4, "label": "XCOMP" }, "lemma": "fear" }, { "text": { "content": "is", "beginOffset": 35 }, "partOfSpeech": { "tag": "VERB", "mood": "INDICATIVE", "number": "SINGULAR", "person": "THIRD", "tense": "PRESENT", }, "dependencyEdge": { "headTokenIndex": 7, "label": "ROOT" }, "lemma": "be" }, { "text": { "content": "fear", "beginOffset": 38 }, "partOfSpeech": { "tag": "NOUN", "number": "SINGULAR", }, "dependencyEdge": { "headTokenIndex": 7, "label": "ATTR" }, "lemma": "fear" }, { "text": { "content": "itself", "beginOffset": 43 }, "partOfSpeech": { "tag": "PRON", "case": "ACCUSATIVE", "gender": "NEUTER", "number": "SINGULAR", "person": "THIRD", }, "dependencyEdge": { "headTokenIndex": 8, "label": "NN" }, "lemma": "itself" }, { "text": { "content": ".", "beginOffset": 49 }, "partOfSpeech": { "tag": "PRON", "case": "ACCUSATIVE", "gender": "NEUTER", "number": "SINGULAR", "person": "THIRD", }, "dependencyEdge": { "headTokenIndex": 8, "label": "NN" }, "lemma": "itself" }, { "text": { "content": ".", "beginOffset": 49 }, "partOfSpeech": { "tag": "PUNCT", }, "dependencyEdge": { "headTokenIndex": 7, "label": "P" }, "lemma": "." } ],
內容分類
您可以使用 Natural Language API 分析文件並傳回符合文件中所出現文字的內容類別清單。如要將文件內容分類，請呼叫 classifyText 方法。
如需 classifyText 方法傳回的內容類別完整清單，請參閱這裡。
Natural Language API 會篩選 classifyText 方法傳回的類別，只納入與要求最相關的類別。舉例來說，如果 /Science 和 /Science/Astronomy 都適用於文件，則只會傳回 /Science/Astronomy 類別，因為這是更具體的結果。
如需 Natural Language API 的內容分類範例，請參閱分類內容。
在單次要求中執行多項作業
如要在單一方法呼叫中執行一組 Natural Language 作業，可以使用 annotateText 做為一般用途的 Natural Language API 要求。文字註解 JSON 要求與標準實體分析要求類似，但還需要傳遞一組功能，指出要對文字執行的作業。以下列出這些功能：
extractDocumentSentiment會執行情緒分析，請參閱「情緒分析」一節的說明。extractEntities會執行實體分析，請參閱「實體分析」一節的說明。extractSyntax表示應處理指定文字才能執行語法分析，請參閱「語法分析」一節的說明。
下列要求會呼叫 API 使用短句為 features 加上註解。
{ "document":{ "type":"PLAIN_TEXT", "content":"The windy, cold weather was unbearable this winter." }, "features":{ "extractSyntax":true, "extractEntities":true, "extractDocumentSentiment":true }, "encodingType":"UTF8" }