Questa pagina fornisce una breve panoramica delle cartelle e spiega come gestire i documenti utilizzando le cartelle.
Motore norme 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 set di regole
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 su descrizione, origine, destinazione e 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 su cui deve essere avviato il controllo della regola. Crea e Aggiorna sono i tipi di trigger supportati.
- Condizione della regola: la condizione che viene valutata dopo il rilevamento di un determinato tipo di trigger. Le condizioni possono essere espresse utilizzando il Common Expression Language (CEL). Ogni condizione deve restituire un output booleano.
- Azioni: insieme di passaggi eseguiti quando la regola è soddisfatta. Quando una condizione della regola viene valutata come vera, viene eseguita l'azione corrispondente (configurata nella regola). Di seguito sono riportati i dettagli di alto livello sulle azioni specifiche implementate in Document Warehouse:
- Azione di convalida dei dati: azione che consente di convalidare campi specifici del documento durante la creazione o l'aggiornamento del documento.
- Azione Aggiornamento 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.
- Elimina azione 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 della regola.
- Azione di inclusione delle cartelle: 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 Rimuovi da 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 dell'accesso (associazione di gruppi e 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.
Gestisci RuleSet
Document Warehouse fornisce API per gestire i RuleSet (creazione, recupero, aggiornamento, eliminazione, elenco). Questa sezione fornisce esempi per la configurazione di diversi tipi di regole.
Creare un insieme di regole
Per creare un insieme 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'API Document AI Warehouse Java.
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.
Elenco di 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"
}
]
}Recupera un set di regole
Per ottenere un insieme di regole utilizzando il nome dell'insieme 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 insieme di regole utilizzando il nome dell'insieme 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 regola
Questa sezione esamina le espressioni delle regole e gli esempi di ogni azione della regola.
Condizioni di esempio
Una condizione si riferisce all'espressione specificata utilizzando il Common Expression Language.
Esempi:
- Espressione del campo stringa
STATE == \'CA\'. Controlla se il valore del campoSTATEè uguale aCANAME != \'\'. Verifica 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 in base 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 precedenti/esistenti e ai nuovi valori delle proprietà dei documenti
Per supportare le condizioni che includono proprietà esistenti e appena fornite, utilizza i seguenti due prefissi con un operatore DOT per accedere alla versione specifica della proprietà:
OLD_per fare riferimento alle proprietà del documento esistenti.NEW_per fare riferimento alle nuove proprietà del documento 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 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 di un documento W9 per la California (campo di testo) STATE:
- Verifica che il campo di testo
NAMEnon sia vuoto. Verifica che
FILING_COST(campo numerico) 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 se assente) un campo
Addressuguale a1600 Amphitheatre Pkwy. Aggiorna (o aggiungi 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 i binding dei criteri che controllano l'accesso al documento
Aggiungi 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 binding 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"]
}
]
}
}
}
}
]
}'Aggiungi regola alla cartella
Quando una cartella viene creata o aggiornata, può essere aggiunta a cartelle statiche predefinite o a cartelle che corrispondono a determinati criteri di ricerca.
Configurare le cartelle statiche
Quando viene creato un nuovo DriverLicense, aggiungilo 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"]
}
}
}
]
}'Pubblica in Pub/Sub
Quando un documento viene creato o aggiornato oppure un link viene creato o eliminato, 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 che segue.
- Richiama le API Document AI Warehouse.
- Verifica che i messaggi siano pubblicati sul canale Pub/Sub.
Regola di esempio
Quando viene aggiunto un documento in 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 Crea documento e Aggiorna documento, la condizione può includere gli attributi del documento in fase di creazione o aggiornamento.
Per i trigger Crea link ed Elimina link, la condizione può includere solo gli attributi del documento 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, insieme 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.