이 페이지에서는 폴더를 간략하게 살펴보고 폴더를 사용하여 문서를 관리하는 방법을 설명합니다.
정책 엔진 및 규칙
Document Warehouse에서 정책 엔진을 사용하면 사용자가 문서를 만들거나 업데이트하는 동안 문서에 대한 일반적인 작업 (예: 유효성 검사 또는 업데이트)을 정의하고 실행할 수 있습니다.
규칙 및 규칙 세트
대략적인 수준에서 규칙 은 다음을 지정하는 사용자 정의 구성을 나타냅니다.
- 규칙 검사를 트리거하는 항목
- 평가되는 조건
- 조건이 충족될 때 실행되는 작업
이러한 사양과 함께 규칙에는 설명, 소스, 대상, 트리거링 조건에 대한 정보가 포함됩니다.
규칙의 논리적 모음을 RuleSet 라고 합니다. 예를 들어 동일한 스키마에서 작동하는 규칙을 단일 규칙 세트로 그룹화할 수 있습니다. 고객은 여러 규칙 세트를 정의할 수 있습니다.
규칙은 문서를 만들거나 업데이트하는 동안 사전 정의된 작업을 자동으로 트리거하는 데 유용합니다.
규칙은 세 가지 주요 항목으로 구성됩니다.
- TriggerType: 규칙 검사를 시작해야 하는 이벤트입니다. 만들기 및 업데이트는 지원되는 트리거 유형입니다.
- 규칙 조건: 특정 트리거 유형이 감지된 후 평가되는 조건입니다. 조건은 Common Expression Language (CEL)를 사용하여 표현할 수 있습니다. 각 조건은 불리언 출력으로 평가되어야 합니다.
- 작업: 규칙이 충족될 때 실행되는 단계 집합입니다. 규칙 조건이 true로 평가되면 규칙에 구성된 해당 작업이 실행됩니다. 다음은 Document Warehouse에 구현된 특정 작업에 관한 대략적인 세부정보입니다.
- 데이터 유효성 검사 작업: 문서 생성 또는 업데이트 중에 문서의 특정 필드의 유효성을 검사할 수 있는 작업입니다.
- 데이터 업데이트 작업: 문서 생성 또는 업데이트 중에 문서의 특정 필드를 업데이트할 수 있는 작업입니다. 이러한 업데이트는 규칙 조건이 충족될 때 실행됩니다.
- 문서 삭제 작업: 특정 필드가 규칙 조건을 사용하여 정의된 삭제 기준을 충족할 때 문서 업데이트 중에 문서를 삭제할 수 있는 작업입니다.
- 폴더 포함 작업: 특정 폴더에 새 문서 (또는 업데이트된 문서)를 자동으로 추가하는 작업입니다. 이러한 폴더는 이름을 사용하여 직접 지정할 수 있습니다.
- 폴더에서 삭제 작업: 규칙 수준 조건이 충족될 때 지정된 폴더에서 새 문서를 자동으로 삭제하는 작업입니다.
- 액세스 제어 작업: 문서 생성 중에 액세스 제어 목록 (그룹 및 사용자 결합)을 업데이트할 수 있는 작업입니다. 이러한 업데이트는 규칙 조건이 충족될 때 실행됩니다.
- 게시 작업: 규칙 수준 조건이 충족될 때 특정 메시지를 사용자의 Pub/Sub 채널에 게시하는 작업입니다.
규칙 세트 관리
Document Warehouse는 규칙 세트를 관리하는 API (만들기, 가져오기, 업데이트, 삭제, 나열)를 제공합니다. 이 섹션에서는 다양한 유형의 규칙을 구성하는 샘플을 제공합니다.
규칙 세트 만들기
규칙 세트를 만들려면 다음을 수행합니다.
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"
}
]
}규칙 세트 가져오기
규칙 세트 이름을 사용하여 규칙 세트를 가져오려면 다음을 수행합니다.
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"
}규칙 세트 삭제
규칙 세트 이름을 사용하여 규칙 세트를 삭제하려면 다음을 수행합니다.
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필드 (float로 정의됨)의 값이10.0보다 큰지 확인합니다.
문서가 특정 스키마에 속하는지 확인하는 방법
특정 스키마 유형을 참조하려면 특수 필드 이름 documentType (예약어)을 사용합니다. DocumentSchema의 DisplayName 필드를 기준으로 평가됩니다.
예:
documentType == \'W9\'
이전 조건은 문서의 스키마 (documentType 키워드 사용)에 W9 표시 이름이 있는지 확인합니다.
이전/기존 문서 속성 값 및 새 문서 속성 값을 참조하는 방법
기존 속성과 새로 제공된 속성을 포함하는 조건을 지원하려면 점 연산자와 함께 다음 두 가지 접두사를 사용하여 속성의 특정 버전에 액세스합니다.
OLD_기존 문서 속성을 참조합니다.NEW_요청의 새 문서 속성을 참조합니다.
예:
OLD_.state == \'TX\' && NEW_.state == \'CA\'상태 속성의 기존 값이TX이고 새로 제공된 값이CA인지 확인합니다.
날짜 필드 처리
DriverLicense 문서의 경우 EXPIRATION_DATE가 특정 날짜 이전인 경우
EXPIRATION_STATUS(enum 필드)를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(float 필드)가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인 경우
Address필드를1600 Amphitheatre Pkwy와 같은 값으로 업데이트하거나 (없는 경우 새로 추가) 합니다.EIN필드를77666666과 같은 값으로 업데이트하거나 (없는 경우 새로 추가) 합니다.
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.
- 링크 만들기 및 삭제 트리거의 경우 알림에는 추가되거나 삭제되는 관련 링크 정보가 포함됩니다.