Text Operations - Analyze Text

服務:

Azure AI Services

API 版本:

2023-10-01

分析文字
用於分析潛在有害文字內容的同步 API。 目前，它支援四種類別：仇恨、自我哈姆、性與暴力。

POST {endpoint}/contentsafety/text:analyze?api-version=2023-10-01

URI 參數

名稱	位於	必要	類型	Description
endpoint	path	True	string	支援的認知服務端點（通訊協定和主機名，例如：https://.cognitiveservices.azure.com).
api-version	query	True	string	要用於這項作業的 API 版本。

要求本文

名稱	必要	類型	Description
text	True	string	要分析的文字。 在一個要求的文字中，我們最多支援 10k 個 Unicode 字元 （Unicode 字碼點）。
blocklistNames		string[]	封鎖清單的名稱。
categories		TextCategory[]	系統會分析類別。 如果未指派它們，則會傳回類別的預設分析結果集。
haltOnBlocklistHit		boolean	設定為 true 時，在封鎖清單遭到點擊的情況下，將不會執行有害內容的進一步分析。 當設定為 false 時，將會執行有害內容的所有分析，無論是否叫用封鎖清單。
outputType		AnalyzeTextOutputType	這是指文字分析輸出的類型。 如果未指派任何值，預設值會是 “FourSeverityLevels”。

回應

名稱	類型	Description
200 OK	AnalyzeTextResult	要求已成功。
Other Status Codes	Azure.Core.Foundations.ErrorResponse	未預期的錯誤回應。 標題 x-ms-error-code: string

安全性

Ocp-Apim-Subscription-Key

類型: apiKey
位於: header

OAuth2Auth

類型: oauth2
Flow: application
權杖 URL: https://login.microsoftonline.com/common/oauth2/v2.0/token

範圍

名稱	Description
https://cognitiveservices.azure.com/.default

範例

Analyze Text

範例要求

HTTP

POST {endpoint}/contentsafety/text:analyze?api-version=2023-10-01

{
  "text": "This is text example"
}

範例回覆

狀態碼:

200

{
  "blocklistsMatch": [],
  "categoriesAnalysis": [
    {
      "category": "Hate",
      "severity": 0
    },
    {
      "category": "SelfHarm",
      "severity": 0
    },
    {
      "category": "Sexual",
      "severity": 0
    },
    {
      "category": "Violence",
      "severity": 0
    }
  ]
}

定義

名稱	Description
AnalyzeTextOptions	文字分析要求。
AnalyzeTextOutputType	這是指文字分析輸出的類型。 如果未指派任何值，預設值會是 “FourSeverityLevels”。
AnalyzeTextResult	文字分析回應。
Azure.Core.Foundations.Error	error 物件。
Azure.Core.Foundations.ErrorResponse	包含錯誤詳細數據的回應。
Azure.Core.Foundations.InnerError	物件，包含有關錯誤的更特定資訊。 根據Microsoft一個 API 指導方針 - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses。
TextBlocklistMatch	封鎖清單比對的結果。
TextCategoriesAnalysis	文字分析結果。
TextCategory	文字內容分析中支持的傷害類別。

AnalyzeTextOptions

文字分析要求。

名稱	類型	預設值	Description
blocklistNames	string[]		封鎖清單的名稱。
categories	TextCategory[]		系統會分析類別。 如果未指派它們，則會傳回類別的預設分析結果集。
haltOnBlocklistHit	boolean		設定為 true 時，在封鎖清單遭到點擊的情況下，將不會執行有害內容的進一步分析。 當設定為 false 時，將會執行有害內容的所有分析，無論是否叫用封鎖清單。
outputType	AnalyzeTextOutputType	FourSeverityLevels	這是指文字分析輸出的類型。 如果未指派任何值，預設值會是 “FourSeverityLevels”。
text	string		要分析的文字。 在一個要求的文字中，我們最多支援 10k 個 Unicode 字元 （Unicode 字碼點）。

AnalyzeTextOutputType

這是指文字分析輸出的類型。 如果未指派任何值，預設值會是 “FourSeverityLevels”。

名稱	類型	Description
EightSeverityLevels	string	八個層級的輸出嚴重性，此值可以是 0,1,2,3,4,5,6,7。
FourSeverityLevels	string	四個層級的輸出嚴重性，此值可以是 0,2,4,6。

AnalyzeTextResult

文字分析回應。

名稱	類型	Description
blocklistsMatch	TextBlocklistMatch[]	封鎖清單符合詳細數據。
categoriesAnalysis	TextCategoriesAnalysis[]	類別的分析結果。

Azure.Core.Foundations.Error

error 物件。

名稱	類型	Description
code	string	其中一組伺服器定義的錯誤碼。
details	Azure.Core.Foundations.Error[]	導致此錯誤之特定錯誤的詳細數據陣列。
innererror	Azure.Core.Foundations.InnerError	物件，包含與目前對象有關錯誤更具體的資訊。
message	string	錯誤的人類可讀取表示法。
target	string	錯誤的目標。

Azure.Core.Foundations.ErrorResponse

包含錯誤詳細數據的回應。

名稱	類型	Description
error	Azure.Core.Foundations.Error	error 物件。

Azure.Core.Foundations.InnerError

物件，包含有關錯誤的更特定資訊。 根據Microsoft一個 API 指導方針 - https://github.com/Microsoft/api-guidelines/blob/vNext/Guidelines.md#7102-error-condition-responses。

名稱	類型	Description
code	string	其中一組伺服器定義的錯誤碼。
innererror	Azure.Core.Foundations.InnerError	內部錯誤。

TextBlocklistMatch

封鎖清單比對的結果。

名稱	類型	Description
blocklistItemId	string	相符項目的識別碼。
blocklistItemText	string	相符項目的內容。
blocklistName	string	相符封鎖清單的名稱。

TextCategoriesAnalysis

文字分析結果。

名稱	類型	Description
category	TextCategory	文字分析類別。
severity	integer	值會隨著輸入內容的嚴重性而增加。 此欄位的值是由要求中指定的輸出類型所決定。 輸出類型可以是 'FourSeverityLevels' 或 'EightSeverity Levels'，輸出值可以是 0、2、4、6 或 0、1、2、3、4、5、6 或 7。

TextCategory

文字內容分析中支持的傷害類別。

名稱	類型	Description
Hate	string	文字 - 仇恨的危害類別。
SelfHarm	string	文字 - SelfHarm 的危害類別。
Sexual	string	文字 - 性傷害類別。
Violence	string	文字 - 暴力的危害類別。