Questa pagina fornisce una breve panoramica delle cartelle e spiega come gestire i documenti utilizzando le cartelle.
Policy Engine e regole
In Document Warehouse, Policy Engine consente agli utenti di definire ed eseguire operazioni comuni sui documenti (ad esempio, convalidare o aggiornare) durante la creazione o l'aggiornamento dei documenti.
Regole e RuleSet
Una regola a livello generale si riferisce a una configurazione definita dall'utente che specifica quanto segue:
- Cosa attiva il controllo delle regole,
- Quale condizione viene valutata e
- Quali azioni vengono eseguite quando la condizione è soddisfatta.
Oltre a queste specifiche, una regola include informazioni sulla descrizione, sull'origine, sul target e sulla condizione di attivazione.
Una raccolta logica di regole è chiamata RuleSet. Ad esempio, le regole che operano sullo stesso schema possono essere raggruppate in un unico RuleSet. I clienti possono definire più RuleSet.
Le regole sono utili per attivare automaticamente azioni predefinite durante la creazione o l'aggiornamento dei documenti.
Una regola è composta da tre elementi principali:
- TriggerType: evento in cui deve essere avviato il controllo delle regole. I tipi di trigger supportati sono Create e Update.
- Condizione della regola: la condizione che viene valutata dopo il rilevamento di un determinato tipo di trigger. Le condizioni possono essere espresse utilizzando Common Expression Language (CEL). Ogni condizione deve restituire un output booleano.
- Azioni: insieme di passaggi eseguiti quando la regola è soddisfatta. Quando una condizione di regola viene valutata come true, viene eseguita l'azione corrispondente (configurata nella regola). Di seguito sono riportati i dettagli generali sulle azioni specifiche implementate in Document Warehouse:
- Azione di convalida dei dati: azione che consente di convalidare campi specifici nel documento durante la creazione o l'aggiornamento del documento.
- Azione di aggiornamento dei dati: azione che consente di aggiornare campi specifici nel documento durante la creazione o l'aggiornamento del documento. Questi aggiornamenti vengono eseguiti quando la condizione della regola è soddisfatta.
- Azione di eliminazione del documento: azione che consente di eliminare il documento durante l'aggiornamento del documento quando determinati campi soddisfano i criteri di eliminazione definiti utilizzando le condizioni delle regole.
- Azione di inclusione della cartella: azione che aggiunge automaticamente un nuovo documento (o un documento aggiornato) in cartelle specifiche. Queste cartelle possono essere specificate direttamente utilizzando il loro nome.
- Azione di rimozione dalla cartella: azione che rimuove automaticamente un nuovo documento dalle cartelle specificate quando viene soddisfatta una condizione a livello di regola.
- Azione di controllo dell'accesso: azione che consente di aggiornare gli elenchi di controllo dell'accesso (gruppi e associazioni di utenti) durante la creazione del documento. Questi aggiornamenti vengono eseguiti quando la condizione della regola è soddisfatta.
- Azione di pubblicazione: azione che pubblica messaggi specifici sul canale Pub/Sub dell'utente quando viene soddisfatta una condizione a livello di regola.
Gestire i RuleSet
Document Warehouse fornisce API per gestire i RuleSet (Create, Get, Update, Delete, List). Questa sezione fornisce esempi per la configurazione di diversi tipi di regole.
Creare un RuleSet
Per creare un set di regole:
REST
Richiesta:
# 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."
}'Risposta
{
"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
Per saperne di più, consulta la documentazione di riferimento dell'API Document AI Warehouse Python.
Per eseguire l'autenticazione in Document AI Warehouse, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Java
Per saperne di più, consulta la Documentazione di riferimento dell'Java API di Document AI Warehouse.
Per eseguire l'autenticazione in Document AI Warehouse, configura le credenziali predefinite dell'applicazione. Per saperne di più, consulta Configura l'autenticazione per un ambiente di sviluppo locale.
Elencare i RuleSet
Per elencare i set di regole in un progetto:
REST
Richiesta:
# 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/ruleSetsRisposta
{
"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"
}
]
}Recuperare un RuleSet
Per recuperare un set di regole utilizzando il nome del set di regole:
REST
Richiesta:
# 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_SETRisposta
{
"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"
}Eliminare un RuleSet
Per eliminare un set di regole utilizzando il nome del set di regole:
REST
Richiesta:
# 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_SETAzioni delle regole
Questa sezione esaminerà le espressioni delle regole e gli esempi di ogni azione delle regole.
Condizioni di esempio
Una condizione si riferisce all'espressione specificata utilizzando Common Expression Language.
Esempi:
- Espressione del campo stringa
STATE == \'CA\'. Controlla se il valore del campoSTATEè uguale aCANAME != \'\'. Controlla che il valore del campoNAMEnon sia vuoto.
- Espressione del campo numerico
FILING_COST > 10.0. Controlla se il valore del campoFILING_COST(definito come float) è maggiore di10.0.
Come verificare se un documento appartiene a uno schema specifico
Per fare riferimento a un tipo di schema specifico, utilizza il nome del campo speciale documentType (è una parola riservata). Viene valutato rispetto al campo DisplayName in DocumentSchema.
Esempio:
documentType == \'W9\'
La condizione precedente verifica se lo schema del documento (utilizzando la parola chiave documentType) ha un nome visualizzato W9.
Come fare riferimento ai valori delle proprietà dei documenti esistenti e ai nuovi valori delle proprietà dei documenti
Per supportare le condizioni che includono proprietà esistenti e appena fornite, utilizza i due prefissi seguenti con un operatore DOT per accedere alla versione specifica della proprietà:
OLD_per fare riferimento alle proprietà dei documenti esistenti.NEW_per fare riferimento alle nuove proprietà dei documenti nella richiesta.
Esempio:
OLD_.state == \'TX\' && NEW_.state == \'CA\'Controlla che il valore esistente della proprietà state siaTXe che il nuovo valore fornito siaCA.
Gestione dei campi data
Per il documento DriverLicense, se EXPIRATION_DATE è precedente a una determinata data
- Aggiorna (o aggiungi un nuovo valore se assente)
EXPIRATION_STATUS(campo enum) con un valore uguale aEXPIRING_BEFORE_CLOSING_DATE.
Per aggiungere valori di data, utilizza la funzione timestamp come mostrato nell'esempio seguente.
REST
Richiesta:
# 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"
}
}
}
}
]
}'Regola di convalida dei dati
Convalida un documento W9 per il campo STATE (campo di testo) California:
- Controlla che il campo
NAME(campo di testo) non sia vuoto. Controlla che il campo
FILING_COST(campo float) sia maggiore di10.0.
REST
Richiesta:
# 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."
}'Regola di aggiornamento dei dati
Per un documento W9, se il campo BUSINESS_NAME è Google:
- Aggiorna (o aggiungi un nuovo valore se assente) un campo
Addressuguale a1600 Amphitheatre Pkwy. Aggiorna (o aggiungi un nuovo valore se assente) un campo
EINuguale a77666666.
REST
Richiesta:
# 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"
}
}
}
}
]
}'Regola di eliminazione dei documenti
Durante l'aggiornamento del documento W9, se il campo BUSINESS_NAME viene modificato in Google, elimina il documento.
REST
Richiesta:
# 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
}
}
}
]
}'Regola di controllo dell'accesso
Durante l'aggiornamento del documento W9, se il campo BUSINESS_NAME è Google, aggiorna le associazioni di policy che controllano l'accesso al documento
Aggiungere una nuova associazione
Quando un documento soddisfa la condizione della regola:
- Aggiunge il ruolo Editor per
user:a@example.comegroup:xxx@example.com Aggiunge il ruolo Visualizzatore per
user:b@example.comegroup:yyy@example.com
REST
Richiesta:
# 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"]
}
]
}
}
}
}
]
}'Sostituire un'associazione esistente
Quando un documento soddisfa la condizione della regola, sostituisci l'associazione esistente in modo da includere solo il ruolo Editor per user:a@example.com e group:xxx@example.com.
REST
Richiesta:
# 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"]
}
]
}
}
}
}
]
}'Aggiungere alla regola della cartella
Quando una cartella viene creata o aggiornata, può essere aggiunta a cartelle statiche predefinite o a cartelle che soddisfano determinati criteri di ricerca.
Configurare le cartelle statiche
Quando viene creata una nuova DriverLicense, aggiungila alla cartella già creata.
REST
Richiesta:
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"]
}
}
}
]
}'Pubblicare in Pub/Sub
Quando un documento viene creato o aggiornato oppure viene creato o eliminato un link, puoi inviare un messaggio di notifica al canale Pub/Sub.
Passaggi per l'utilizzo
- Crea un argomento Pub/Sub nel progetto del cliente.
- Crea una regola per attivare l'azione di pubblicazione Pub/Sub utilizzando la seguente richiesta. (Vedi l'esempio seguente.)
- Richiama le API Document AI Warehouse.
- Verifica che i messaggi siano pubblicati sul canale Pub/Sub.
Esempio di regola
Quando un documento viene aggiunto a una cartella (viene richiamata l'API CreateLink), è possibile utilizzare la seguente regola per inviare messaggi di notifica all'argomento Pub/Sub.
REST
Richiesta:
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."
}
}
}
]
}'Dettagli regola
Questa azione è supportata per i seguenti tipi di trigger:
ON_CRATE: quando viene creato un nuovo documento.ON_UPDATE: quando il documento viene aggiornato.ON_CRATE_LINK: quando viene creato un nuovo link.ON_DELETE_LINK: quando un link viene eliminato.
Per i trigger di creazione e aggiornamento dei documenti, la condizione può includere gli attributi del documento in fase di creazione o aggiornamento.
Per i trigger di creazione ed eliminazione dei link, la condizione può includere solo gli attributi del documento della cartella da cui viene aggiunto o rimosso il documento.
Il campo
messagespuò essere utilizzato per inviare un elenco di messaggi al canale Pub/Sub. Tieni presente che, oltre a questi messaggi, per impostazione predefinita vengono pubblicati anche i seguenti campi:- Nome schema, nome documento, tipo di trigger, nome RuleSet, ID regola, ID azione.
- Per i trigger di creazione ed eliminazione dei link, le notifiche includono le informazioni sui link pertinenti che vengono aggiunti o eliminati.