ドキュメントモデレーション 2.0 API - Content Moderation - Alibaba Cloud ドキュメントセンター

ドキュメントモデレーション 2.0 API は、一般的なドキュメントにおけるリスクや違反のモデレーションに役立ちます。このトピックでは、ドキュメントモデレーション 2.0 で呼び出すことができる操作について説明します。

アクセスガイドライン

Alibaba Cloud アカウントを登録します。今すぐ登録表示される手順に従ってアカウント登録を完了します。
Content Moderation の従量課金方式を有効にします。Content Moderation 2.0 サービスが有効になっていることを確認します。詳細については、「サービスを有効にする」をご参照ください。有効化は無料です。このサービスの有効化は課金されません。API 操作を呼び出すと、課金システムによって使用量に基づいて自動的に課金されます。
AccessKey ペアを作成します。Resource Access Management（RAM）ユーザーとして AccessKey ペアを作成していることを確認します。詳細については、「AccessKey を作成する」をご参照ください。RAM ユーザーの AccessKey ペアを使用する場合は、Alibaba Cloud アカウントを使用して、AliyunYundunGreenWebFullAccess 権限を RAM ユーザーに付与します。詳細については、「RAM 権限付与」をご参照ください。
SDK を使用します。SDK を使用して API を呼び出すことをお勧めします。詳細については、「ドキュメントモデレーション 2.0 SDK と統合ガイド」をご参照ください。

モデレーションタスクを送信する

使用上の注意

ビジネス運用: FileModeration。ドキュメントでは非同期モデレーション操作のみを提供しています。

サポートされているリージョンとアクセスアドレス。

リージョン	パブリックネットワークアクセスアドレス	内部ネットワークアクセスアドレス	サポートされているサービス
シンガポール	green-cip.ap-southeast-1.aliyuncs.com	green-cip-vpc.ap-southeast-1.aliyuncs.com	document_detection_global

課金情報:
この操作は課金対象であり、ドキュメントで処理されたページ数に基づいて課金されます。
モデレーション対象: 一般的なドキュメントのモデレーションがサポートされています。
サンプル出力: 非同期モデレーションリクエストを送信した場合、モデレーション結果はリアルタイムで返されません。モデレーション結果を取得するには、モデレーション結果を定期的にポーリングするか、コールバック通知を有効にすることができます。モデレーション結果は最大 24 時間保持されます。
- コールバック通知を有効にしてモデレーション結果を取得する: 非同期モデレーションタスクを送信するときに、でモデレーション結果を受信するためのコールバック URL を指定できます。
  コールバック パラメーターのモデレーションリクエスト。
- モデレーション結果をポーリングする: 非同期モデレーションタスクを送信するときに callback パラメーターを設定する必要はありません。タスクを送信した後、結果クエリ操作を呼び出してモデレーション結果をクエリできます。
ドキュメントの要件:
- サポートされているプロトコル: HTTP および HTTPS。
- サポートされている形式: DOC、DOCX、PPT、PPTX、PPS、PPSX、PDF、XLS、XLSX、XLTX、XLTM、HTML、および TXT (UTF-8 エンコーディング)。
- ドキュメントサイズ制限: 個々のドキュメントは 200 MB を超えてはなりません。この制限を超えるドキュメントは圧縮または分割してください。
- モデレーション時間はドキュメントのダウンロード時間によって異なります。ドキュメントのストレージサービスが安定していて信頼できることを確認してください。ドキュメントストレージには Alibaba Cloud OSS をお勧めします。
モデレーション ルールの構成:
- 最初に呼び出す前に、Content Moderation コンソールでドキュメントモデレーションルールを構成する必要があります。この構成がない場合、ドキュメントモデレーション 2.0 API はデフォルトで標準設定になります。

QPS 制限

この操作は、アカウントごとに 1 秒あたり最大 100 回呼び出すことができます。システムは最大 20 の同時モデレーションタスクをサポートしています。この制限を超えるリクエストは破棄され、サービス中断が発生します。この操作を呼び出すときは、この制限に注意することをお勧めします。

デバッグ

アクセスする前に、Alibaba Cloud OpenAPI を使用してドキュメントモデレーション 2.0 操作のオンラインデバッグを行い、サンプルコード、SDK の依存関係を表示し、操作の使用法とパラメーターについて理解してください。

重要

Content Moderation API を呼び出す前に、Alibaba Cloud アカウントを使用して Content Moderation コンソールにログインする必要があります。そのため、操作の呼び出しによって発生した料金はアカウントに請求されます。

リクエストパラメーター

名前

タイプ

必須

例

説明

Service

String

はい

document_detection_global

モデレーションサービスのタイプ。例:

document_detection_global: 一般ドキュメントモデレーション

ServiceParameters

JSONString

はい

モデレーションサービスに必要なパラメーターセット。値は JSON 文字列です。文字列の説明については、ServiceParameters をご参照ください。

表 1. ServiceParameters

名前	タイプ	必須	例	説明
url	String	必須。ドキュメントモデレーション 2.0 は、ドキュメントを追加する 3 つの方法をサポートしています。いずれか 1 つを選択してください。モデレーションにドキュメント URL メソッドを使用し、url を指定します。モデレーションに OSS 認証を使用します。 ossBucketName、ossObjectName、および ossRegionId を同時に指定する必要があります。モデレーションにローカルドキュメントを使用します。ローカルドキュメントファイルをモデレーション用にアップロードします。これは OSS ストレージ容量を占有せず、ファイルは 30 分間だけ保存されます。SDK アクセスには、ローカルドキュメントのアップロード機能が統合されています。具体的なコード例については、「ドキュメントモデレーション 2.0 SDK とアクセスガイド」をご参照ください。	http://www.aliyundoc.com/a.pdf	モデレーション対象のオブジェクトの URL。URL がパブリックネットワーク経由でアクセス可能であり、URL アドレスの長さが 2048 文字を超えないことを確認してください。説明 URL アドレスには漢字を含めることはできず、1 つのリクエストに対して 1 つの URL のみが指定されていることを確認してください。
ossBucketName	String		bucket_0307	承認済みの OSS バケットの名前。説明 OSS ビデオイントラネットアドレスを使用する場合は、最初に Alibaba Cloud アカウント (つまりメインアカウント) を使用してクラウドリソースアクセス認証ページにアクセスして認証を行う必要があります。
ossObjectName	String		20240307/07/28/test.pdf	承認済みの OSS バケット内のオブジェクトの名前。
ossRegionId	String		cn-shanghai	OSS バケットのリージョン。
docType	String	いいえ	pdf	URL によって提供されるドキュメントが接尾辞のないファイルの場合、ドキュメント形式を指定する必要があります。有効な値は、doc、docx、ppt、pptx、pps、ppsx、xls、xlsx、xltx、xltm、xlsb、xlsm、csv、pdf、html、txt です。説明ドキュメントタイプが txt 形式の場合、テキストコンテンツのみがモデレートされ、画像コンテンツはスクリーンショットによってモデレートされません。txt 形式のドキュメントからテキストを直接抽出し、テキストモデレーション 2.0 サービスを呼び出すことをお勧めします。
callback	String	いいえ	http://www.aliyundoc.com	モデレーション結果のコールバック通知用 URL。HTTP および HTTPS プロトコルを使用するアドレスをサポートしています。このフィールドが空の場合、モデレーション結果を定期的にポーリングする必要があります。コールバック操作は、POST メソッド、UTF-8 エンコードされた送信データ、およびフォームパラメーター checksum と content をサポートしている必要があります。 Content Moderation は、次のルールと形式に従って checksum と content を設定し、コールバック操作を呼び出してモデレーション結果を返します。チェックサム: 文字列形式で、`user uid + seed + content` で構成され、SHA256 アルゴリズムによって生成されます。ユーザー UID は Alibaba Cloud アカウント ID であり、Alibaba Cloud 管理コンソールでクエリできます。データ改ざんを防ぐために、サーバーがコールバック通知を受信したときに SHA-256 アルゴリズムを使用して文字列を生成し、その文字列を受信したチェックサム値と照合できます。説明 UID は Alibaba Cloud アカウントの ID でなければならず、RAM ユーザーの ID ではありません。 content: JSON 形式の文字列。コールバックデータを JSON 形式に解析します。content パラメーターの形式の詳細については、非同期モデレーション結果をクエリするために呼び出すことができる各操作の成功応答の例をご参照ください。説明サーバーがコールバック通知を受信した場合、サーバーは HTTP 200 ステータスコードを Content Moderation に送信します。サーバーがコールバック通知の受信に失敗した場合、サーバーは他の HTTP ステータスコードを Content Moderation に送信します。サーバーがコールバック通知の受信に失敗した場合、Content Moderation はサーバーがコールバック通知を受信するまでコールバック通知のプッシュを続けます。Content Moderation は、コールバック通知を最大 16 回繰り返しプッシュできます。16 回後、Content Moderation はコールバック通知のプッシュを停止します。この場合、コールバック URL のステータスを確認することをお勧めします。
seed	String	いいえ	abc****	コールバック通知リクエストの署名を生成するために使用されるランダムな文字列。文字列の長さは最大 64 文字で、文字、数字、およびアンダースコア (_) を含めることができます。この文字列はカスタマイズできます。これは、Content Moderation がサーバーにコールバック通知をプッシュするときに、コールバック通知リクエストを検証するために使用されます。説明 callback パラメーターを設定する場合、このパラメーターは必須です。
cryptType	String	いいえ	SHA256	コールバック通知を有効にしたときにコールバック通知コンテンツに署名するために使用されるアルゴリズム。Content Moderation は、指定したアルゴリズムを使用して返された文字列に署名し、署名付き文字列をコールバック URL に送信します。返される文字列は UID + シード + コンテンツ形式です。有効な値: SHA256 (デフォルト): SHA256 暗号化アルゴリズムを使用します。 SM3: 国の機密 HMAC-SM3 暗号化アルゴリズムを使用し、16 進文字列を返します。文字列は小文字と数字で構成されます。たとえば、HMAC-SM3 暗号化アルゴリズムを使用して abc を暗号化すると、66c7f0f462eeedd9d1f2d46bdc10e4e24167c4875cf2f7a2297da02b8f4ba8e0 が返されます。
dataId	String	いいえ	fileId****	モデレーション対象のオブジェクトの ID。 ID には、文字、数字、アンダースコア (_)、ハイフン (-)、およびピリオド (.) を含めることができます。長さは最大 128 文字です。この ID は、ビジネスデータを一意に識別します。
referer	String	いいえ	www.aliyun.com	リファラーリクエストヘッダー。ホットリンク保護などのシナリオで使用されます。値の長さは最大 256 文字です。

レスポンスパラメーター

名前		タイプ	例	説明
Code		Integer	200	ステータスコード。HTTP ステータスコードと一致します。詳細については、コードの説明をご参照ください。
Data		JSONObject		モデレーション結果データ。
	TaskId	String	AAAAA-BBBBB	モデレーションのタスク ID。
Message		String	OK	リクエストメッセージのレスポンスメッセージ。
RequestId		String	ABCD1234-1234-1234-1234-123****	リクエスト ID。

例

リクエストの例

{
  "Service": "document_detection_global",
  "ServiceParameters":
  {
    "url": "http://www.aliyundoc.com/a.pdf",
    "dataId": "fileId-2024-0307-0728***"
  }
}

成功レスポンスの例

{
    "Msg": "OK",
    "Code": 200,
    "Data":
    {
        "TaskId": "AAAAA-BBBBB-CCCCCCCC"
    },
    "RequestId": "ABCD1234-1234-1234-1234-123****"
}

ドキュメントモデレーションタスクの結果を取得する

使用上の注意

ビジネス運用: DescribeFileModerationResult。ドキュメントモデレーションタスクの結果を取得します。

課金情報: この操作は課金されません。
クエリタイムアウト: 非同期モデレーションリクエストを送信してから少なくとも 30 秒後にモデレーション結果をクエリすることをお勧めします。Content Moderation は、モデレーション結果を最大 24 時間保持します。4 時間後、結果は自動的に削除されます。

QPS 制限

この操作は、アカウントごとに 1 秒あたり最大 100 回呼び出すことができます。1 秒あたりの呼び出し数がこの制限を超えると、スロットリングがトリガーされます。これはビジネス運用に影響を与える可能性があります。そのため、この操作を呼び出すときは、この制限に注意することをお勧めします。

デバッグ

アクセスする前に、Alibaba Cloud OpenAPI を使用して操作のオンラインデバッグを行い、サンプルコード、SDK の依存関係を表示し、操作の使用法とパラメーターについて理解してください。

リクエストパラメーター

名前	タイプ	必須	例	説明
Service	String	はい	document_detection	モデレーションサービスのタイプ。送信されたモデレーションタスクのモデレーションサービスのタイプと一致する必要があります。
ServiceParameters	JSONString	はい		モデレーションサービスに必要なパラメーター。値は JSON 文字列です。各文字列の説明については、ServiceParameters をご参照ください。

表 1. ServiceParameters

名前	タイプ	必須	例	説明
taskId	string	はい	abcd****	クエリするタスクの ID。一度に 1 つのタスク ID を指定できます。説明モデレーションタスクを送信した後、レスポンスからタスクの ID を取得できます。

レスポンスパラメーター

名前	タイプ	例	説明
RequestId	String	ABCD1234-1234-1234-1234-123****	リクエスト ID。問題の特定とトラブルシューティングに使用されます。
Data	Object		ドキュメントコンテンツのモデレーション結果。詳細については、Data をご参照ください。
Code	String	200	ステータスコード。HTTP ステータスコードと一致します。詳細については、コードの説明をご参照ください。
Message	String	OK	このリクエストのレスポンスメッセージ。

表 2. Data

名前	タイプ	例	説明
DataId	String	fileId****	モデレーション対象のオブジェクトの ID。説明リクエストで DataId パラメーターを指定した場合、DataId パラメーターの値がレスポンスで返されます。
Url	String	http://www.aliyundoc.com/a.docx	モデレーション対象の URL。
DocType	String	pdf	接尾辞のないファイルに指定された形式。有効な値は、doc、docx、ppt、pptx、pps、ppsx、xls、xlsx、xltx、xltm、xlsb、xlsm、csv、pdf、html、txt です。
PageSummary	Object		ドキュメントモデレーション結果の概要。構造の詳細については、PageSummary をご参照ください。
RiskLevel	String	high	リスクレベル。画像とテキストの総合的な計算に基づいて返されます。戻り値は次のとおりです。 high: 高リスク medium: 中リスク low: 低リスク none: リスクなし説明次の処理方法が推奨されます。お客様は高リスクのコンテンツを直接処理します。中リスクのコンテンツは手動でレビューする必要があります。低リスクのコンテンツは、よりリスクの高いコンテンツが検出された場合に処理できます。お客様は、リスクが検出されなかったコンテンツをビジネス要件に基づいて処理できます。リスクスコアは Content Moderation コンソールで構成できます。
PageResult	JSONArray		ドキュメントページのモデレーション結果。呼び出しが成功した場合 (code=200)、モデレーション結果には構造が含まれます。構造の詳細については、PageResult をご参照ください。説明 HTTP ステータスコード 280 は、モデレーションタスクが進行中であることを示し、HTTP ステータスコード 200 は、モデレーションタスクが完了したことを示します。モデレーションタスクが進行中の場合、返されるモデレーション結果には、Content Moderation がタスクで検出したすべての問題が含まれます。

表 3. PageSummary

名前	タイプ	例	説明
PageSum	Integer	10	ドキュメントでモデレートされたページの総数。
ImageSummary	Object		画像モデレーション結果の概要。構造の詳細については、ImageSummary をご参照ください。説明ドキュメントファイルが txt 形式の場合、画像モデレーション結果は存在しません。
TextSummary	Object		テキストモデレーション結果の概要。構造の詳細については、TextSummary をご参照ください。

表 4. ImageSummary

名前

タイプ

例

説明

RiskLevel

String

high

リスクレベル。構成されたリスクスコアに基づいて返されます。有効な値:

high: 高リスク
medium: 中リスク
low: 低リスク
none: リスクなし

ImageLabels

JSONArray

画像ラベルの概要。構造の詳細については、ImageLabels をご参照ください。

表 5. ImageLabels

名前	タイプ	例	説明
Label	String	violent_explosion	画像リスクラベル。詳細については、リスクラベル解釈表をご参照ください。
LabelSum	Integer		ラベルの出現回数
Description	String	花火のコンテンツ	Label フィールドの説明。説明このフィールドは Label フィールドの説明であり、変更される場合があります。実際の結果を処理する際には Label フィールドを処理することをお勧めします。このフィールドに基づいて結果を処理しないでください。

表 6. TextSummary

名前

タイプ

例

説明

RiskLevel

String

high

ドキュメントテキストのリスクレベル。戻り値は次のとおりです。

high: 高リスク
medium: 中リスク
low: 低リスク
none: リスクなし

TextLabels

JSONArray

テキストラベルの概要。具体的な構造については、TextLabels をご参照ください。

表 7. TextLabels

名前	タイプ	例	説明
Label	String	violent_explosion	テキストリスクラベル。
LabelSum	Integer		ラベルが一致した回数。

表 8. PageResult

名前	タイプ	例	説明
PageNum	Integer	50	ドキュメントのページ数。
ImageUrl	String	http://oss.aliyundoc.com/a.png	現在のページのスクリーンショットの URL リンク。
ImageResult	JSONArray		現在のページの画像モデレーション結果。構造の詳細については、ImageResult をご参照ください。説明ドキュメントファイルが txt 形式の場合、画像モデレーション結果は存在しません。
TextResult	JSONArray		現在のページのテキストモデレーション結果。構造の詳細については、TextResult をご参照ください。

表 9. ImageResult

名前	タイプ	例	説明
Description	String	ドキュメントページの画像コンテンツのモデレーション	画像の説明。
Service	String	baselineCheck	画像に対して呼び出されたサービス。
RiskLevel	String	high	リスクレベル。構成されたリスクスコアに基づいて返されます。有効な値: high: 高リスク medium: 中リスク low: 低リスク none: リスクなし
Location	JSONObject	{"x":0,"y":0,"w":100,"h":100}	(予約済み) 画像パーツの座標
LabelResult	JSONArray		画像に対して返されたラベル。構造の詳細については、LabelResult をご参照ください。

表 10. LabelResult

名前	タイプ	例	説明
Label	String	violent_explosion	画像モデレーション後に返されるラベル。同じスクリーンショットに対して複数のラベルとスコアがモデレートされる場合があります。詳細については、リスクラベル解釈表をご参照ください。
Confidence	Float	81.22	信頼レベルのスコア。有効な値: 0 ～ 100。値は小数点以下 2 桁まで正確です。
Description	String	花火のコンテンツ	Label フィールドの説明。説明このフィールドは Label フィールドの説明であり、変更される場合があります。このフィールドではなく、Label フィールドに基づいてモデレーション結果を処理することをお勧めします。

表 11. TextResult

名前	タイプ	例	説明
Description	String	ドキュメントページのテキストコンテンツのモデレーション。	テキストパーツの説明。
Service	String	pgc_detection	テキストパーツに対して呼び出されたサービス。
Text	String	これはテキストパーツです	テキストパーツのコンテンツ。
Labels	String	ad_compliance,C_customized	テキストパーツに対して返されたラベル。詳細については、テキストモデレーション 2.0 によって提供される多言語サービスをご参照ください。
RiskWords	String	リスクワード A、リスクワード B	テキストパーツに対して返されたリスクワード。
RiskTips	String	広告法_極端な言葉の一般的な禁止	テキストパーツに対して返されたサブラベル。
RiskLevel	String	high	リスクレベル。計算されたテキストリスクに基づいて返されます。有効な値: high: 高リスク medium: 中リスク low: 低リスク none: リスクなし

例

リクエストの例

{
    "service": "document_detection_global",
    "serviceParameters": {
        "taskId": "abcd****"
    }
}

成功レスポンスの例

{
    "Code": 200,
    "Data": {
        "DataId": "fileId-2024-0307-0728***",
        "PageResult": [
            {
                "ImageResult": [
                    {
                        "Description": "ドキュメントページの画像コンテンツのモデレーション",
                        "LabelResult": [
                            {
                                "label": "nonLabel"
                            }
                        ],
                        "Service": "baselineCheck_global"
                    }
                ],
                "ImageUrl": "http://oss.aliyundoc.com/a.png",
                "PageNum": 1,
                "TextResult": [
                    {
                        "Description": "ドキュメントページのテキストコンテンツのモデレーション",
                        "Labels": "",
                        "RiskTips": "",
                        "RiskWords": "",
                        "Service": "comment_multilingual_global",
                        "Text": "Content Moderation プロダクトテストケース a"
                    }
                ]
            },
            ...
            {
                "ImageResult": [
                    {
                        "Description": "ドキュメントページの画像コンテンツのモデレーション",
                        "LabelResult": [
                            {
                                "Confidence": 89.01,
                                "Label": "pornographic_adultContent_tii"
                            }
                        ],
                        "Service": "baselineCheck_global"
                    }
                ],
                "ImageUrl": "http://oss.aliyundoc.com/b.png",
                "PageNum": 10,
                "TextResult": [
                    {
                        "Description": "ドキュメントページのテキストコンテンツのモデレーション",
                        "Labels": "contraband,sexual_content",
                        "RiskTips": "禁止_禁止商品、ポルノ_映画リソース、ポルノ_わいせつ",
                        "RiskWords": "リスクワード A、リスクワード B",
                        "Service": "comment_multilingual_global",
                        "Text": "Content Moderation プロダクトテストケース b"
                    }
                ]
            }
        ],
        "Url": "http://www.aliyundoc.com/a.docx"
    },
    "Message": "SUCCESS",
    "RequestId": "1D0854A7-AAAAA-BBBBBBB-CC8292AE5"
}

コードの説明

ドキュメントモデレーション 2.0 操作によって返されるコードの意味を以下に詳述します。コード 200 と 280 のリクエストのみが測定および課金されます。その他のコードは課金対象外です。

コード	説明
200	リクエストは正常であるか、モデレーションは完了しています。
280	モデレーションは進行中です。
400400	すべてのリクエストパラメーターが構成されているわけではありません。
401	リクエストパラメーターが無効です。
402	リクエストパラメーターが無効です。確認して修正し、再試行してください。
403	リクエストの QPS が上限を超えています。一度に送信されるリクエスト数を確認して修正してください。
404	指定されたファイルのダウンロードに失敗しました。ファイルの URL を確認するか、再試行してください。
405	指定されたファイルのダウンロードまたは変換がタイムアウトしました。リンクにアクセスできない可能性があります。ファイルを確認して調整し、再試行してください。
406	指定されたファイルが大きすぎます。ファイルサイズを確認して調整し、再試行してください。
407	指定されたファイルの形式はサポートされていません。ファイル形式を確認して変更し、再試行してください。
408	必要な権限がありません。このアカウントが有効になっていないか、支払いが延滞しているか、この API 操作を呼び出す権限がない可能性があります。
409	指定された RequestId は存在しません。モデレーション結果が 24 時間の有効期間を超えている可能性があります。
480	同時モデレーションタスクの数が上限を超えています。同時モデレーションタスクの数を確認して変更してください。
500	システム例外が発生しました。