Cette page présente brièvement les dossiers et explique comment gérer les documents à l'aide de dossiers.
Moteur de stratégies et règles
Dans Document Warehouse, le moteur de stratégies permet aux utilisateurs de définir et d'exécuter des opérations courantes sur des documents (par exemple, valider ou mettre à jour) lors de la création ou de la mise à jour de documents.
Règles et ensembles de règles
Une règle de haut niveau 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écutées lorsque la condition est remplie.
Outre 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 qui fonctionnent sur le même schéma peuvent être regroupées dans un seul ensemble de règles. 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éclencheurs compatibles sont "Créer" et "Mettre à jour".
- 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 sortie booléenne.
- Actions : ensemble d'étapes exécutées lorsque la règle est remplie. Lorsqu'une condition de règle est évaluée comme "true", l'action correspondante (configurée dans la règle) est exécutée. Voici les détails de haut niveau concernant les actions spécifiques implémentées dans Document Warehouse :
- Action de validation des données : action qui permet de valider des champs spécifiques du document lors de sa création ou de sa mise à jour.
- 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 mise à jour. 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 la 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 de suppression 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 qui permet de mettre à jour les listes de contrôle des accès (liaisons de groupes et d'utilisateurs) lors de la création du 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 pour 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 ensemble de règles
Pour créer un ensemble de règles, procédez comme suit :
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 PythonDocument AI Warehouse.
Pour vous authentifier auprès de Document AI Warehouse, configurez le service 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 le service 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 ensemble de règles
Pour supprimer 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 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érifie si la valeur du champSTATEest égale àCA.NAME != \'\'. Vérifie que la valeur du champNAMEn'est pas vide.
- Expression de champ numérique
FILING_COST > 10.0. Vérifie si la valeur du champFILING_COST(défini comme flottant) 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é). Il est évalué par rapport au champ DisplayName dans 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é de document et aux nouvelles valeurs de propriété de document
Pour prendre en charge les conditions qui incluent des propriétés existantes et nouvellement fournies, 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 de 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.
Gérer les champs de date
Pour le document DriverLicense, si la EXPIRATION_DATE est antérieure à une certaine date
- Mettez à jour (ou ajoutez si elle n'existe pas)
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 l'état STATE (champ de texte) de la Californie :
- Vérifiez que le champ
NAME(champ de texte) n'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 Google :
- Mettez à jour (ou ajoutez si elle n'existe pas) un champ
Addrességal à1600 Amphitheatre Pkwy. Mettez à jour (ou ajoutez si elle n'existe pas) 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 document
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 règles 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 d'éditeur pour
user:a@example.cometgroup:xxx@example.com. Ajoute le rôle de 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 répond à la condition de la règle, remplacez la liaison existante pour n'inclure que le rôle d'é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 d'ajout 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 nouveau 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.
Étapes à suivre
- Créez un sujet Pub/Sub dans le projet client.
- Créez une règle pour déclencher l'action de publication Pub/Sub à l'aide de la requête suivante. (Consultez l'exemple suivant.)
- 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 au 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 compatible avec les types de déclencheurs suivants :
ON_CRATE: lorsqu'un nouveau document est créé.ON_UPDATE: lorsque le document est mis à jour.ON_CRATE_LINK: lorsqu'un nouveau lien est créé.ON_DELETE_LINK: lorsqu'un lien est supprimé.
Pour les déclencheurs de création et de mise à jour de documents, la condition peut inclure des attributs du document en cours de création ou de mise à jour.
Pour les déclencheurs de création et de suppression de liens, la condition ne peut inclure que des attributs du document de 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 de l'ensemble de règles, ID de la règle, ID de l'action.
- Pour les déclencheurs de création et de suppression de liens, les notifications incluent les informations de lien pertinentes qui sont ajoutées ou supprimées.