Cette page présente brièvement les dossiers et explique comment gérer les documents à l'aide de dossiers.
Moteur de règles et règles
Dans l'Entrepôt de documents, le moteur de règles permet aux utilisateurs de définir et d'exécuter des opérations courantes sur les documents (par exemple, valider ou mettre à jour) lors de la création ou de la modification de documents.
Règles et ensembles de règles
De manière générale, une règle fait référence à une configuration définie par l'utilisateur qui spécifie les éléments suivants :
- ce qui déclenche la vérification des règles ;
- la condition évaluée ;
- les actions à exécuter lorsque la condition est remplie.
En plus de ces spécifications, une règle inclut des informations sur la description, la source, la cible et la condition de déclenchement.
Un ensemble logique de règles est appelé RuleSet. Par exemple, les règles fonctionnant sur le même schéma peuvent être regroupées dans un seul RuleSet. Les clients peuvent définir plusieurs ensembles de règles.
Les règles sont utiles pour déclencher automatiquement des actions prédéfinies lors de la création ou de la mise à jour de documents.
Une règle se compose de trois éléments principaux :
- TriggerType : événement sur lequel la vérification de la règle doit être lancée. Les types de déclencheur "Créer" et "Mettre à jour" sont acceptés.
- Condition de la règle : condition évaluée après la détection d'un certain type de déclencheur. Les conditions peuvent être exprimées à l'aide du CEL (Common Expression Language). Chaque condition doit renvoyer une valeur booléenne.
- Actions : ensemble d'étapes exécutées lorsque la règle est respectée. Lorsqu'une condition de règle est évaluée comme "true", l'action correspondante (configurée dans la règle) est exécutée. Vous trouverez ci-dessous des informations générales sur les actions spécifiques implémentées dans Document Warehouse :
- Action de validation des données : action permettant de valider des champs spécifiques du document lors de sa création ou de sa modification.
- Action de mise à jour des données : action qui permet de mettre à jour des champs spécifiques du document lors de sa création ou de sa modification. Ces mises à jour sont exécutées lorsque la condition de la règle est remplie.
- Action de suppression de document : action qui permet de supprimer le document lors de sa mise à jour lorsque certains champs répondent aux critères de suppression définis à l'aide des conditions de règle.
- Action d'inclusion de dossier : action qui ajoute automatiquement un nouveau document (ou un document mis à jour) dans des dossiers spécifiques. Ces dossiers peuvent être spécifiés directement à l'aide de leur nom.
- Action "Supprimer du dossier" : action qui supprime automatiquement un nouveau document de dossiers donnés lorsqu'une condition au niveau de la règle est remplie.
- Action de contrôle des accès : action permettant de mettre à jour les listes de contrôle des accès (associations de groupes et d'utilisateurs) lors de la création d'un document. Ces mises à jour sont exécutées lorsque la condition de la règle est remplie.
- Action de publication : action qui publie des messages spécifiques sur le canal Pub/Sub de l'utilisateur lorsqu'une condition au niveau de la règle est remplie.
Gérer les ensembles de règles
Document Warehouse fournit des API permettant de gérer les ensembles de règles (créer, obtenir, mettre à jour, supprimer, lister). Cette section fournit des exemples de configuration de différents types de règles.
Créer un RuleSet
Pour créer un ensemble de règles :
REST
Requête :
# 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."
}'Réponse
{
"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
Pour en savoir plus, consultez la documentation de référence de l'API Document AI Warehouse Python.
Pour vous authentifier auprès de Document AI Warehouse, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Java
Pour en savoir plus, consultez la documentation de référence de l'API Document AI Warehouse Java.
Pour vous authentifier auprès de Document AI Warehouse, configurez les Identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.
Lister les ensembles de règles
Pour lister les ensembles de règles d'un projet, procédez comme suit :
REST
Requête :
# 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/ruleSetsRéponse
{
"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"
}
]
}Obtenir un ensemble de règles
Pour obtenir un ensemble de règles à l'aide de son nom, procédez comme suit :
REST
Requête :
# 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_SETRéponse
{
"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"
}Supprimer un RuleSet
Pour supprimer un ensemble de règles à l'aide de son nom :
REST
Requête :
# 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_SETActions de la règle
Cette section présente les expressions de règles et des exemples d'actions de règles.
Exemples de conditions
Une condition fait référence à l'expression spécifiée à l'aide du CEL (Common Expression Language).
Exemples :
- Expression de champ de chaîne
STATE == \'CA\'. Vérifiez si la valeur du champSTATEest égale àCA.NAME != \'\'Vérifiez que la valeur du champNAMEn'est pas vide.
- Expression de champ numérique
FILING_COST > 10.0. Vérifiez si la valeur du champFILING_COST(défini comme un float) est supérieure à10.0.
Vérifier si un document appartient à un schéma spécifique
Pour faire référence à un type de schéma spécifique, utilisez le nom de champ spécial documentType (il s'agit d'un mot réservé). Elle est évaluée par rapport au champ DisplayName de DocumentSchema.
Exemple :
documentType == \'W9\'
La condition précédente vérifie si le schéma du document (à l'aide du mot clé documentType) a un nom à afficher de W9.
Faire référence aux anciennes/existantes valeurs de propriétés de document et aux nouvelles valeurs de propriétés de document
Pour prendre en charge les conditions qui incluent des propriétés existantes et nouvellement attribuées, utilisez les deux préfixes suivants avec un opérateur DOT pour accéder à la version spécifique de la propriété :
OLD_pour faire référence aux propriétés de document existantes.NEW_pour faire référence aux nouvelles propriétés du document dans la requête.
Exemple :
OLD_.state == \'TX\' && NEW_.state == \'CA\'Vérifie que la valeur existante de la propriété d'état estTXet que la nouvelle valeur fournie estCA.
Gestion des champs de date
Pour le document DriverLicense, si le EXPIRATION_DATE est antérieur à une certaine date
- Mettez à jour (ou ajoutez si absent)
EXPIRATION_STATUS(champ d'énumération) avec une valeur égale àEXPIRING_BEFORE_CLOSING_DATE.
Pour ajouter des valeurs de date, utilisez la fonction d'horodatage, comme indiqué dans l'exemple suivant.
REST
Requête :
# 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"
}
}
}
}
]
}'Règle de validation des données
Validez un document W9 pour le champ de texte STATE (Californie) :
- Vérifiez que le champ de texte
NAMEn'est pas vide. Vérifiez que le champ
FILING_COST(champ flottant) est supérieur à10.0.
REST
Requête :
# 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."
}'Règle de mise à jour des données
Pour un document W9, si le champ BUSINESS_NAME est défini sur "Google" :
- Mettez à jour (ou ajoutez si absent) un champ
Addrességal à1600 Amphitheatre Pkwy. Mettez à jour (ou ajoutez si absent) un champ
EINégal à77666666.
REST
Requête :
# 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"
}
}
}
}
]
}'Règle de suppression de documents
Lors de la mise à jour du document W9, si le champ BUSINESS_NAME est remplacé par Google, supprimez le document.
REST
Requête :
# 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
}
}
}
]
}'Règle de contrôle des accès
Lors de la mise à jour du document W9, si le champ BUSINESS_NAME est Google, mettez à jour les liaisons de stratégie qui contrôlent l'accès au document.
Ajouter une liaison
Lorsqu'un document répond à la condition de la règle :
- Ajoute le rôle Éditeur pour
user:a@example.cometgroup:xxx@example.com Ajoute le rôle Lecteur pour
user:b@example.cometgroup:yyy@example.com
REST
Requête :
# 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"]
}
]
}
}
}
}
]
}'Remplacer une liaison existante
Lorsqu'un document satisfait à la condition de la règle, remplacez la liaison existante pour n'inclure que le rôle Éditeur pour user:a@example.com et group:xxx@example.com.
REST
Requête :
# 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"]
}
]
}
}
}
}
]
}'Règle "Ajouter au dossier"
Lorsqu'un dossier est créé ou mis à jour, il peut être ajouté sous des dossiers statiques prédéfinis ou des dossiers correspondant à certains critères de recherche.
Configurer des dossiers statiques
Lorsqu'un DriverLicense est créé, ajoutez-le au dossier déjà créé.
REST
Requête :
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"]
}
}
}
]
}'Publier dans Pub/Sub
Lorsqu'un document est créé ou mis à jour, ou qu'un lien est créé ou supprimé, vous pouvez envoyer un message de notification au canal Pub/Sub.
Procédure d'utilisation
- Créez un sujet Pub/Sub dans le projet client.
- Créez une règle pour déclencher l'action Pub/Sub de publication à l'aide de la requête suivante. (Consultez l'exemple ci-dessous.)
- Appelez les API Document AI Warehouse.
- Vérifiez que les messages sont publiés sur le canal Pub/Sub.
Exemple de règle
Lorsqu'un document est ajouté à un dossier (l'API CreateLink est appelée), la règle suivante peut être utilisée pour envoyer des messages de notification à un sujet Pub/Sub.
REST
Requête :
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."
}
}
}
]
}'Détails de la règle
Cette action est disponible pour les types de déclencheurs suivants :
ON_CRATE: lorsqu'un document est créé.ON_UPDATE: date de mise à jour du document.ON_CRATE_LINK: lorsqu'un lien est créé.ON_DELETE_LINK: lorsqu'un lien est supprimé.
Pour les déclencheurs "Créer un document" et "Mettre à jour un document", la condition peut inclure des attributs du document en cours de création ou de modification.
Pour les déclencheurs "Créer un lien" et "Supprimer un lien", la condition ne peut inclure que les attributs du document "Dossier" à partir duquel le document est ajouté ou supprimé.
Le champ
messagespeut être utilisé pour envoyer une liste de messages au canal Pub/Sub. Notez qu'en plus de ces messages, les champs suivants sont également publiés par défaut :- Nom du schéma, nom du document, type de déclencheur, nom du RuleSet, ID de la règle, ID de l'action
- Pour les déclencheurs de lien "Créer" et "Supprimer", les notifications incluent les informations pertinentes sur le lien qui est ajouté ou supprimé.