このページでは、フォルダの概要と、フォルダを使用してドキュメントを管理する方法について説明します。
ポリシー エンジンとルール
Document Warehouse のポリシー エンジンを使用すると、ドキュメントの作成または更新時に、ドキュメントに対する一般的なオペレーション(検証や更新など)を定義して実行できます。
ルールとルールセット
ルールは、次の内容を指定するユーザー定義の構成を指します。
- ルールのチェックをトリガーする条件、
- どの条件が評価されるか、
- 条件が満たされたときに実行されるアクション。
これらの仕様に加えて、ルールには説明、ソース、ターゲット、トリガー条件の情報が含まれます。
ルールの論理的なコレクションは RuleSet と呼ばれます。RuleSetたとえば、同じスキーマで動作するルールを 1 つの RuleSet にグループ化できます。お客様は複数の RuleSet を定義できます。
ルールは、ドキュメントの作成または更新時に、事前定義されたアクションを自動的にトリガーする場合に便利です。
ルールは主に次の 3 つで構成されます。
- TriggerType: ルールチェックを開始するイベント。サポートされているトリガータイプは Create と Update です。
- ルール条件: 特定のトリガー タイプが検出された後に評価される条件。条件は Common Expression Language(CEL)を使用して表現できます。各条件はブール値の出力に評価される必要があります。
- アクション: ルールが満たされたときに実行される一連のステップ。ルール条件が true と評価されると、対応するアクション(ルールで構成)が実行されます。Document Warehouse で実装される特定のアクションの概要は次のとおりです。
- データ検証アクション: ドキュメントの作成または更新時に、ドキュメント内の特定のフィールドを検証できるようにするアクション。
- データ更新アクション: ドキュメントの作成または更新時にドキュメント内の特定のフィールドを更新できるアクション。このような更新は、ルールの条件が満たされたときに実行されます。
- ドキュメント削除アクション: 特定のフィールドがルール条件で定義された削除条件を満たした場合に、ドキュメントの更新中にドキュメントを削除できるアクション。
- フォルダ包含アクション: 特定のフォルダに新しいドキュメント(または更新されたドキュメント)を自動的に追加するアクション。このようなフォルダは、名前を使用して直接指定できます。
- フォルダから削除アクション: ルールレベルの条件が満たされたときに、指定されたフォルダから新しいドキュメントを自動的に削除するアクション。
- アクセス制御アクション: ドキュメントの作成時にアクセス制御リスト(グループとユーザー バインディング)の更新を許可するアクション。このような更新は、ルールの条件が満たされたときに実行されます。
- パブリッシュ アクション: ルールレベルの条件が満たされたときに、特定のメッセージをユーザーの Pub/Sub チャネルにパブリッシュするアクション。
ルールセットを管理する
Document Warehouse には、RuleSet を管理するための API(作成、取得、更新、削除、一覧表示)が用意されています。このセクションでは、ルールのさまざまなタイプを構成するサンプルを示します。
RuleSet を作成する
ルールセットを作成する手順は次のとおりです。
REST
リクエスト:
# Create a RuleSet for data validation.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
"rules": [
{
"trigger_type": "ON_CREATE",
"condition": "documentType == \'W9\' && STATE ==\'CA\'",
"actions": {
"data_validation": {
"conditions": {
"NAME": "NAME != \'\'",
"FILING_COST": "FILING_COST > 10.0"
}
}
},
"enabled": true
}
],
"description": "W9: Basic validation check rules."
}'レスポンス
{
"description": "W9: Basic validation check rules.",
"name": "RULE_SET_NAME",
"rules": [
{
"actions": [
{
"actionId": "de0e6b84-106b-44ba-b1c4-0b3ad6ddc719",
"dataValidation": {
"conditions": {
"FILING_COST": "FILING_COST > 10.0",
"NAME": "NAME != ''"
}
}
}
],
"condition": "documentType == 'W9' && STATE =='CA'",
"enabled": true,
"triggerType": "ON_CREATE"
}
]
}
Python
詳細については、Document AI Warehouse Python API リファレンス ドキュメントをご覧ください。
Document AI Warehouse に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Java
詳細については、Document AI Warehouse Java API リファレンス ドキュメントをご覧ください。
Document AI Warehouse に対する認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
ルールセットを一覧表示する
プロジェクトのルールセットを一覧表示する手順は次のとおりです。
REST
リクエスト:
# List all rule-sets for a project.
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSetsレスポンス
{
"ruleSets": [
{
"description": "W9: Basic validation check rules.",
"rules": [
{
"triggerType": "ON_CREATE",
"condition": "documentType == 'W9' && STATE =='CA'",
"actions": [
{
"actionId": "fcf79ae8-9a1f-4462-9262-eb2e7161350c",
"dataValidation": {
"conditions": {
"NAME": "NAME != ''",
"FILING_COST": "FILING_COST > 10.0"
}
}
}
],
"enabled": true
}
],
"name": "RULE_SET_NAME"
}
]
}RuleSet を取得する
ルールセット名を使用してルールセットを取得する手順は次のとおりです。
REST
リクエスト:
# Get a rule-set using rule-set ID.
curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets/RULE_SETレスポンス
{
"description": "W9: Basic validation check rules.",
"rules": [
{
"triggerType": "ON_CREATE",
"condition": "documentType == 'W9' && STATE =='CA'",
"actions": [
{
"actionId": "7559346b-ec9f-4143-ab1c-1912f5588807",
"dataValidation": {
"conditions": {
"NAME": "NAME != ''",
"FILING_COST": "FILING_COST > 10.0"
}
}
}
],
"enabled": true
}
],
"name": "RULE_SET_NAME"
}RuleSet を削除する
ルールセット名を使用してルールセットを削除するには、次の操作を行います。
REST
リクエスト:
# Get a rule-set using rule-set ID.
curl -X DELETE -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets/RULE_SETルールのアクション
このセクションでは、ルール式と各ルール アクションの例について説明します。
サンプル条件
条件とは、Common Expression Language を使用して指定された式を指します。
例:
- 文字列フィールド式
STATE == \'CA\'。STATEフィールドの値がCAと等しいかどうかを確認します。NAME != \'\'。NAMEフィールドの値が空でないことを確認します。
- 数値フィールド式
FILING_COST > 10.0。FILING_COSTフィールド(浮動小数点として定義)の値が10.0より大きいかどうかを確認します。
ドキュメントが特定のスキーマに属しているかどうかを確認する方法
特定のスキーマタイプを参照するには、特別なフィールド名 documentType(予約語)を使用します。これは DocumentSchema の DisplayName フィールドに対して評価されます。
例:
documentType == \'W9\'
上記の条件は、ドキュメントのスキーマ(キーワード documentType を使用)に W9 という表示名があるかどうかを確認します。
古いドキュメントのプロパティ値と新しいドキュメントのプロパティ値を参照する方法
既存のプロパティと新しく付与されたプロパティを含む条件をサポートするには、次の 2 つの接頭辞をドット演算子とともに使用して、プロパティの特定のバージョンにアクセスします。
- 既存のドキュメント プロパティを参照する
OLD_。 NEW_: リクエストで新しいドキュメントのプロパティを参照します。
例:
OLD_.state == \'TX\' && NEW_.state == \'CA\'状態プロパティの既存の値がTXで、指定された新しい値がCAであることを確認します。
日付フィールドの処理
DriverLicense ドキュメントの場合、EXPIRATION_DATE が特定の日付より前の場合
EXPIRATION_STATUS(列挙型フィールド)をEXPIRING_BEFORE_CLOSING_DATEと等しい値で更新します(存在しない場合は新規追加します)。
日付値を追加するには、次の例に示すようにタイムスタンプ関数を使用します。
REST
リクエスト:
# Check if document expires before a date and update the status field
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
"rules":[
{
"trigger_type": "ON_CREATE",
"description": "Expiration date check rule",
"condition": "documentType==\'DriverLicense\' && EXPIRATION_DATE < timestamp(\'2021-08-01T00:00:00Z\')",
"actions": {
"data_update": {
"entries": {
"EXPIRATION_STATUS": "EXPIRING_BEFORE_CLOSING_DATE"
}
}
}
}
]
}'データの入力規則
STATE(テキスト フィールド)カリフォルニアの W9 ドキュメントを検証します。
NAME(テキスト フィールド)が空でないことを確認します。FILING_COST(浮動小数点フィールド)が10.0より大きいことを確認します。
REST
リクエスト:
# Rules for data validation.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
"rules": [
{
"trigger_type": "ON_CREATE",
"condition": "documentType == \'W9\' && STATE ==\'CA\'",
"actions": {
"data_validation": {
"conditions": {
"NAME": "NAME != \'\'",
"FILING_COST": "FILING_COST > 10.0"
}
}
},
"enabled": true
}
],
"description": "W9: Basic validation check rules."
}'データ更新ルール
W9 ドキュメントの場合、BUSINESS_NAME フィールドが Google の場合:
1600 Amphitheatre Pkwyと等しいAddressフィールドを更新します(存在しない場合は新規追加します)。77666666と等しいEINフィールドを更新します(存在しない場合は新規追加します)。
REST
リクエスト:
# Rule for data update.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
"rules":[
{
"description": "W9: Rule to update address data and EIN.",
"trigger_type": "ON_CREATE",
"condition": "documentType==\'W9\' && BUSINESS_NAME == \'Google\'",
"actions": {
"data_update": {
"entries": {
"Address": "1600 Amphitheatre Pkwy",
"EIN": "776666666"
}
}
}
}
]
}'ドキュメント削除ルール
W9 ドキュメントの更新中に、BUSINESS_NAME フィールドが Google に変更された場合は、ドキュメントを削除します。
REST
リクエスト:
# Rule for deleting the document
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
"rules": [
{
"description": "W9: Rule to delete the document during update.",
"trigger_type": "ON_UPDATE",
"condition": "documentType == \'W9\' && BUSINESS_NAME == \'Google\'",
"actions": {
"delete_document_action": {
"enable_hard_delete": true
}
}
}
]
}'アクセス制御ルール
W9 ドキュメントの更新中に、BUSINESS_NAME フィールドが Google の場合は、ドキュメントへのアクセスを制御するポリシー バインディングを更新します。
新しいバインディングを追加する
ドキュメントがルール条件を満たす場合:
user:a@example.comとgroup:xxx@example.comの編集者ロールを追加user:b@example.comとgroup:yyy@example.comの閲覧者ロールを追加
REST
リクエスト:
# Rule for adding new policy binding while creating the document.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
"rules": [
{
"description": "W9: Rule to add new policy binding."
"trigger_type": "ON_CREATE",
"condition": "documentType == \'aca13aa9-6d0d-4b6b-a1eb-315dcb876bd1\' && BUSINESS_NAME == \'Google\'",
"actions": {
"access_control": {
"operation_type": "ADD_POLICY_BINDING",
"policy": {
"bindings": [
{
"role": "roles/contentwarehouse.documentEditor",
"members": ["user:a@example.com", "group:xxx@example.com"]
},
{
"role": "roles/contentwarehouse.documentViewer",
"members": ["user:b@example.com", "group:yyy@example.com"]
}
]
}
}
}
}
]
}'既存のバインディングを置き換える
ドキュメントがルール条件を満たしている場合、既存のバインディングを置き換えて、user:a@example.com と group:xxx@example.com の編集者ロールのみを含めます。
REST
リクエスト:
# Rule for replacing existing policy bindings with newly given bindings.
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
"rules": [
{
"description": "W9: Rule to replace policy binding."
"trigger_type": "ON_CREATE",
"condition": "documentType == \'a9e37d07-9cfa-4b4d-b372-53162e3b8bd9\' && BUSINESS_NAME == \'Google\'",
"actions": {
"access_control": {
"operation_type": "REPLACE_POLICY_BINDING",
"policy": {
"bindings": [
{
"role": "roles/contentwarehouse.documentEditor",
"members": ["user:a@example.com", "group:xxx@example.com"]
}
]
}
}
}
}
]
}'フォルダ ルールに追加
フォルダを作成または更新すると、事前に定義された静的フォルダまたは特定の検索条件に一致するフォルダの下に追加できます。
静的フォルダを構成する
新しい DriverLicense が作成されたら、すでに作成されているフォルダに追加します。
REST
リクエスト:
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
"rules": [
{
"trigger_type": "ON_CREATE",
"condition": "documentType == \'DriverLicense\'",
"actions": {
"add_to_folder": {
"folders": ["projects/821411934445/locations/us/documents/445en119hqp70"]
}
}
}
]
}'Pub/Sub に公開
ドキュメントが作成または更新されたとき、またはリンクが作成または削除されたときに、Pub/Sub チャネルに通知メッセージをプッシュできます。
使用手順
- 顧客プロジェクトに Pub/Sub トピックを作成します。
- 次のリクエストを使用して、Pub/Sub アクションの公開をトリガーするルールを作成します。(次の例をご覧ください)。
- Document AI Warehouse API を呼び出す。
- メッセージが Pub/Sub チャンネルにパブリッシュされることを確認します。
ルールの例
フォルダにドキュメントが追加されたとき(CreateLink API が呼び出されたとき)に、次のルールを使用して Pub/Sub トピックに通知メッセージを送信できます。
REST
リクエスト:
curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/ruleSets \
-d '{
"rules": [
{
"trigger_type": "ON_CREATE_LINK",
"condition": "documentType == \'DriverLicenseFolder\'",
"actions": {
"publish_to_pub_sub": {
"topic_id": "<topic_name>"
"messages": "Added document under a folder."
}
}
}
]
}'ルールの詳細
このアクションは、次のトリガータイプでサポートされています。
ON_CRATE: 新しいドキュメントが作成されたとき。ON_UPDATE: ドキュメントが更新されたとき。ON_CRATE_LINK: 新しいリンクが作成されたとき。ON_DELETE_LINK: リンクが削除されたとき。
ドキュメントの作成と更新のトリガーの場合、条件には作成または更新されるドキュメントの属性を含めることができます。
リンクの作成と削除のトリガーの場合、条件に含めることができるのは、ドキュメントの追加または削除元のフォルダ ドキュメントの属性のみです。
messagesフィールドを使用して、メッセージのリストを Pub/Sub チャネルに送信できます。なお、これらのメッセージとともに、デフォルトでは次のフィールドも公開されます。- スキーマ名、ドキュメント名、トリガータイプ、ルールセット名、ルール ID、アクション ID。
- リンクの作成と削除のトリガーの場合、通知には追加または削除される関連リンクの情報が含まれます。