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