本文件提供使用 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 要求來執行情緒分析和實體分析。
歡迎試用
如果您未曾使用過 Google Cloud，歡迎建立帳戶，親自體驗實際使用 Natural Language 的成效。新客戶可以獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。
免費試用 Natural Language基本的 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並未針對documentSentiment進行標準化處理；只要文字內容出現情緒用字 (無論正負面) 都會提高文字的magnitude值 (因此文字篇幅較長，幅度值可能也會較大)。
- 情緒的
language_code提供文件的語言資訊，可在初始要求中傳遞，亦可由系統自動偵測 (如果沒有的話)。language_supported包含布林值，用於識別系統是否正式支援該語言sentences提供從原始文件中擷取的語句清單，其中包含：sentiment提供各個語句的「語句整體情緒」值，其中score介於-1.0(負面) 和1.0(正面) 之間，magnitude值則介於0.0和1.0之間。請注意，sentences的magnitude已標準化。
蓋茨堡宣言的情緒值為 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" }