Guide de démarrage rapide

Ce guide décrit toutes les étapes de configuration nécessaires pour commencer à utiliser Document AI Warehouse.

À propos de la console Google Cloud

Google Cloud console est une interface utilisateur Web permettant de provisionner, configurer, gérer et surveiller les systèmes qui utilisent des produits Google Cloud . Vous utilisez la consoleGoogle Cloud pour configurer et gérer les ressources Document AI Warehouse.

Créer un projet

Pour utiliser les services fournis par Google Cloud, vous devez créer un projet.

Un projet permet d'organiser toutes vos ressources Google Cloud . Un projet se compose des éléments suivants :

Un ensemble de collaborateurs
Des API activées (et autres ressources)
Outils de surveillance
Informations bancaires
L'authentification et le contrôle des accès

Vous pouvez créer un projet ou en créer plusieurs. Vous pouvez utiliser vos projets pour organiser vos ressources Google Cloud dans une hiérarchie des ressources. Pour en savoir plus sur les projets, consultez la documentation Resource Manager.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Roles required to select or create a project

Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

Go to project selector

Activer la facturation

Un compte de facturation sert à déterminer qui assume les frais pour un ensemble de ressources donné. Il peut être associé à un ou plusieurs projets. Les frais d'utilisation du projet sont imputés au compte de facturation associé. Vous pouvez configurer la facturation lorsque vous créez un projet. Pour en savoir plus, consultez la documentation sur la facturation.

Verify that billing is enabled for your Google Cloud project.

Provisionner et initialiser le service

Avant d'utiliser Document AI Warehouse pour la première fois, vous devez provisionner et initialiser les ressources associées à votre projet sur la page de provisionnement Document AI Warehouse.

Si vous souhaitez provisionner les ressources, vous devez disposer des rôles Administrateur Content Warehouse et Administrateur d'utilisation du service du projet.

Procédure de provisionnement

Sélectionnez une région.

Sur la page de provisionnement, sélectionnez la région que vous souhaitez activer.

Chaque région est indépendante. Par conséquent, si vous souhaitez utiliser plusieurs régions, provisionnez chacune d'elles séparément.
Activez l'API principale. {:#enable-core-api}:

Cliquez sur Activer. Cela permet d'activer les API Document AI Warehouse dans votre projet.

Une fois l'API activée, cliquez sur Suivant.

Provisionnez l'instance.

Cette étape provisionne la ressource pour votre projet dans le service Document AI Warehouse. Vous devez choisir parmi trois modes de contrôle des accès. Examinez-les attentivement pour sélectionner les modes adaptés à votre cas d'utilisation. Pour en savoir plus, consultez la page sur le mode de contrôle des accès.

Sélectionnez un mode de contrôle des accès (LCA).

[Recommandé] Contrôle des accès au niveau des documents pour les utilisateurs Cloud Identity.

Ce mode est approprié si votre organisation gère les utilisateurs ou les groupes dans le service Cloud Identity.
- L'interface Document AI Warehouse est compatible avec ce mode pour authentifier les utilisateurs.
- Les utilisateurs et les groupes LDAP et Active Directory de votre organisation peuvent être synchronisés avec Cloud Identity.
- Les utilisateurs Google Workspace peuvent être facilement ajoutés à Cloud Identity.
Contrôle des accès au niveau des documents pour les utilisateurs du service d'identité BYOID.

Si vous ne pouvez pas ajouter vos utilisateurs à Cloud Identity ni les synchroniser avec le service, utilisez ce mode. Toutefois :
- L'interface Document AI Warehouse n'est pas compatible avec ce mode. Vous aurez peut-être besoin d'une application cliente personnalisée.
- Votre application cliente personnalisée authentifie les utilisateurs auprès du fournisseur d'identité et transmet les utilisateurs et leur appartenance à des groupes à l'aide de l'API Document AI Warehouse.
Accès universel : aucun contrôle des accès au niveau des documents.
- L'interface Document AI Warehouse est compatible avec ce mode pour authentifier les utilisateurs.
- Ce mode est généralement utilisé pour accorder l'accès aux utilisateurs publics sans authentification requise.
- Les portails personnalisés peuvent accéder à tous les documents à l'aide d'un compte de service doté du rôle souhaité (le rôle "Lecteur de documents", par exemple) et transmettre cet accès aux utilisateurs publics sans authentification.

	Contrôle des accès au niveau des documents pour les utilisateurs Cloud Identity	Contrôle des accès au niveau des documents pour les utilisateurs du service d'identité BYOID	Accès universel
Accès au niveau du document	Oui	Oui	Non
Compatibilité avec l'UI de Document AI Warehouse	Oui	Non	Oui (si les utilisateurs ont accès au niveau du projet)

Activez les questions et réponses :

Cochez Questions et réponses si vous souhaitez activer la recherche par IA générative dans votre projet. Pour en savoir plus, y compris sur la façon d'être ajouté à la liste d'autorisation pour utiliser la fonctionnalité, consultez Recherche par IA générative.

Déclenchement du provisionnement :

Cliquez sur Provisionner pour commencer à provisionner votre projet. La configuration de l'instance prendra un certain temps (trois à cinq minutes).
Créez un schéma par défaut.

Cliquez sur Créer lors de l'étape d'initialisation. Cela crée un schéma par défaut qui peut être utilisé pour les fichiers PDF ou TXT extraits par OCR. Il contient le champ de texte brut pour l'indexation, mais pas de propriétés.
Afficher l'instance :

Le processus de provisionnement est terminé. Si votre projet utilise le contrôle des accès au niveau du document, passez à la section suivante pour configurer les autorisations au niveau du projet.

Si vous êtes sur la liste d'autorisation des fonctionnalités de l'interface utilisateur de la console Google Cloud , vous pouvez cliquer sur Commencer pour commencer à utiliser Document AI Warehouse dans la console Google Cloud .

Si vous ne figurez pas sur la liste d'autorisation des fonctionnalités de l'interface utilisateur de la console Google Cloud , vous pouvez passer à la section Configurer l'application Web pour savoir comment configurer l'application Web Document AI Warehouse.
Configurez les autorisations requises dans IAM pour vos utilisateurs. Si le contrôle des accès au niveau des documents est activé, des autorisations au niveau du projet et des autorisations IAM sont requises. Pour en savoir plus, consultez la section Autorisations requises.

Configurer des autorisations au niveau du projet

Si votre projet active le contrôle des accès au niveau du document (option 1 dans la sélection du mode LCA), vous devez accorder à votre compte administrateur ainsi qu'à vos utilisateurs des autorisations au niveau du projet.

Pour ce faire, dans la vue finale après le provisionnement, accédez à Autorisations du projet :

Suivez les étapes ci-dessous pour ajouter votre compte administrateur en tant qu'administrateur de documents :

Cliquez sur Ajouter un utilisateur.
Saisissez l'adresse e-mail de votre administrateur, puis sélectionnez le niveau d'accès Administrateur de documents. Cliquez sur Enregistrer.
Pour les autres utilisateurs, vous pouvez les ajouter en tant que :
1. Administrateur de documents : rôle qui permet d'accéder à tous les documents du projet, y compris de les importer, de les afficher, de les modifier et de les supprimer, quels que soient leurs propriétaires. De plus, les administrateurs de documents peuvent modifier les autorisations de tous les documents.
2. Éditeur de documents : rôle qui permet d'afficher et de modifier tous les documents, mais pas d'en créer ni d'en supprimer dans le projet, ni de modifier les autorisations des documents.
3. Lecteur de documents : rôle qui n'accorde que les autorisations de lecture pour tous les documents. Les lecteurs de documents ne peuvent pas créer, modifier ni supprimer des documents, ni en modifier les autorisations.
4. Créateur de documents : rôle qui n'autorise que l'importation de documents. Les créateurs de documents disposent de toutes les autorisations pour les documents qu'ils importent, mais n'ont aucune autre autorisation pour les autres documents, sauf s'ils obtiennent des autorisations explicites pour ces documents.
Il peut s'agir de l'adresse e-mail d'un utilisateur ou d'un groupe. Choisissez Groupe dans le champ Type lorsque vous spécifiez une adresse e-mail de groupe.

Remarque : Document AI Warehouse n'est pas compatible avec l'extension de l'accès aux sous-groupes. Si des autorisations sont accordées au groupe, les utilisateurs doivent être des enfants directs du groupe.

Autorisations requises

Dans Document AI Warehouse, nous disposons d'un système ACL indépendant en plus d'IAM. Pour les projets LCA au niveau du document, vous devez obtenir des autorisations supplémentaires au niveau du projet dans le système LCA de Document AI Warehouse. Pour les projets à accès universel, seules les autorisations IAM sont requises.

Vous trouverez ci-dessous des tableaux récapitulatifs des autorisations requises :

Projets de LCA de document

Type d’utilisateur	Rôle IAM	Autorisations au niveau du projet de Document AI Warehouse
Administrateurs	Administrateur Content Warehouse	Administrateur de documents
Utilisateurs normaux	Lecteur de schémas de documents Content Warehouse	Créateur/Éditeur/Lecteur de documents, selon les autorisations souhaitées

Projets d'accès universel

Type d’utilisateur	Rôle IAM
Administrateurs	1. Administrateur Content Warehouse 2. Administrateur de documents Content Warehouse
Utilisateurs normaux	1. Lecteur de schémas de documents Content Warehouse 2. Créateur/Lecteur/Éditeur de documents Content Warehouse, selon les autorisations souhaitées

Rôles IAM pour les projets d'accès universel

Nom du rôle	Nom du rôle	Objectif
Créateur de documents Content Warehouse	`contentwarehouse.documentCreator`	Créer des documents
Lecteur de documents Content Warehouse	`contentwarehouse.documentViewer`	Afficher des documents
Éditeur de documents Content Warehouse	`contentwarehouse.documentEditor`	Modifier des documents (sans les créer ni les supprimer)
Administrateur de documents Content Warehouse	`contentwarehouse.documentAdmin`	Gérer les documents (y compris les créer et les supprimer)
Administrateur Content Warehouse	`contentwarehouse.admin`	Gérer les documents, les schémas et les règles

Pour en savoir plus, consultez Rôles et autorisations IAM.

Configurer le jeton d'accès (pour appeler l'API depuis la ligne de commande)

Pour appeler l'API Document AI Warehouse avec des outils de ligne de commande, procédez comme suit.

Utiliser le fichier de clé de compte de service dans votre environnement

Provide authentication credentials to your application code by setting the environment variable GOOGLE_APPLICATION_CREDENTIALS. This variable applies only to your current shell session. If you want the variable to apply to future shell sessions, set the variable in your shell startup file, for example in the ~/.bashrc or ~/.profile file.

Linux ou macOS

export GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Replace KEY_PATH with the path of the JSON file that contains your credentials.

For example:

export GOOGLE_APPLICATION_CREDENTIALS="/home/user/Downloads/service-account-file.json"

Windows

For PowerShell:

$env:GOOGLE_APPLICATION_CREDENTIALS="KEY_PATH"

Replace KEY_PATH with the path of the JSON file that contains your credentials.

For example:

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\Users\username\Downloads\service-account-file.json"

For command prompt:

set GOOGLE_APPLICATION_CREDENTIALS=KEY_PATH

Replace KEY_PATH with the path of the JSON file that contains your credentials.

Installer et initialiser Google Cloud CLI (facultatif)

La gcloud CLI fournit un ensemble d'outils qui vous permet de gérer les ressources et les applications hébergées sur Google Cloud.

Le lien suivant fournit des instructions :

Installez la Google Cloud CLI. Une fois que la Google Cloud CLI est installée, initialisez-la en exécutant la commande suivante :

gcloud init

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

Générer le jeton d'accès

Si vous avez configuré l'authentification lors des étapes précédentes, vous pouvez utiliser Google Cloud CLI pour tester votre environnement d'authentification. Exécutez la commande suivante et vérifiez qu'aucune erreur ne se produit et que les identifiants sont bien renvoyés :

AUTH_TOKEN=$(gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/cloud-platform)

Vérifiez que AUTH_TOKEN est défini, par exemple :

$ echo $AUTH_TOKEN
ya29.c.b0AXv0zTPvXmEMZXCe781qL0Y3r1EKnw3k4DJcoWGZkyWKx-nMNVQVErQ3ge6XA2RXsTU1tf_SMLgeWC6xwS51tP8QZhbypuGczBzMgKWYExwATHt3Vn553edl8tmqCMjROgdQjCDd8i7as-236r4d8gNwKsR192gNgNw_0zzs0MPyNVmqydpfmpj8yBwJI5QWna1331GTGKgd3Ia16fTzAHrZC_GkcO0wJPo....................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................................

Tester l'appel de l'API Document AI Warehouse

La commande AUTH_TOKEN est utilisée par tous les exemples REST de l'API Document AI Warehouse pour authentifier les appels d'API. Par exemple, la commande suivante récupère tous les schémas de document que vous avez définis et qui sont associés à votre projet (dans la plupart des cas, utilisez "us" comme emplacement) :

  curl --header "Authorization: Bearer $AUTH_TOKEN" https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER>/locations/LOCATION/documentSchemas

Exemples de code

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.

public class QuickStart {

  public static void main(String[] args)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "your-project-id";
    String location = "your-region"; // Format is "us" or "eu".
    String userId = "your-user-id"; // Format is user:<user-id>
    quickStart(projectId, location, userId);
  }

  public static void quickStart(String projectId, String location, String userId)
      throws IOException, InterruptedException, ExecutionException, TimeoutException {
    String projectNumber = getProjectNumber(projectId);

    String endpoint = "contentwarehouse.googleapis.com:443";
    if (!"us".equals(location)) {
      endpoint = String.format("%s-%s", location, endpoint);
    }
    DocumentSchemaServiceSettings documentSchemaServiceSettings = 
         DocumentSchemaServiceSettings.newBuilder().setEndpoint(endpoint).build(); 

    // Create a Schema Service client
    try (DocumentSchemaServiceClient documentSchemaServiceClient =
        DocumentSchemaServiceClient.create(documentSchemaServiceSettings)) {
      /*  The full resource name of the location, e.g.:
      projects/{project_number}/locations/{location} */
      String parent = LocationName.format(projectNumber, location);

      /* Create Document Schema with Text Type Property Definition
       * More detail on managing Document Schemas: 
       * https://cloud.google.com/document-warehouse/docs/manage-document-schemas */
      DocumentSchema documentSchema = DocumentSchema.newBuilder()
          .setDisplayName("My Test Schema")
          .setDescription("My Test Schema's Description")
          .addPropertyDefinitions(
            PropertyDefinition.newBuilder()
              .setName("test_symbol")
              .setDisplayName("Searchable text")
              .setIsSearchable(true)
              .setTextTypeOptions(TextTypeOptions.newBuilder().build())
              .build()).build();

      // Define Document Schema request
      CreateDocumentSchemaRequest createDocumentSchemaRequest =
          CreateDocumentSchemaRequest.newBuilder()
            .setParent(parent)
            .setDocumentSchema(documentSchema).build();

      // Create Document Schema
      DocumentSchema documentSchemaResponse =
          documentSchemaServiceClient.createDocumentSchema(createDocumentSchemaRequest); 


      // Create Document Service Client Settings
      DocumentServiceSettings documentServiceSettings = 
          DocumentServiceSettings.newBuilder().setEndpoint(endpoint).build();

      // Create Document Service Client and Document with relevant properties 
      try (DocumentServiceClient documentServiceClient =
          DocumentServiceClient.create(documentServiceSettings)) {
        TextArray textArray = TextArray.newBuilder().addValues("Test").build();
        Document document = Document.newBuilder()
              .setDisplayName("My Test Document")
              .setDocumentSchemaName(documentSchemaResponse.getName())
              .setPlainText("This is a sample of a document's text.")
              .addProperties(
                Property.newBuilder()
                  .setName(documentSchema.getPropertyDefinitions(0).getName())
                  .setTextValues(textArray)).build();

        // Define Request Metadata for enforcing access control
        RequestMetadata requestMetadata = RequestMetadata.newBuilder()
            .setUserInfo(
            UserInfo.newBuilder()
              .setId(userId).build()).build();

        // Define Create Document Request 
        CreateDocumentRequest createDocumentRequest = CreateDocumentRequest.newBuilder()
            .setParent(parent)
            .setDocument(document)
            .setRequestMetadata(requestMetadata)
            .build();

        // Create Document
        CreateDocumentResponse createDocumentResponse =
            documentServiceClient.createDocument(createDocumentRequest);

        System.out.println(createDocumentResponse.getDocument().getName());
        System.out.println(documentSchemaResponse.getName());
      }
    }
  }

  private static String getProjectNumber(String projectId) throws IOException { 
    try (ProjectsClient projectsClient = ProjectsClient.create()) { 
      ProjectName projectName = ProjectName.of(projectId); 
      Project project = projectsClient.getProject(projectName);
      String projectNumber = project.getName(); // Format returned is projects/xxxxxx
      return projectNumber.substring(projectNumber.lastIndexOf("/") + 1);
    } 
  }
}

Node.js

Pour en savoir plus, consultez la documentation de référence de l'API Document AI Warehouse Node.js.

/**
 * TODO(developer): Uncomment these variables before running the sample.
 * const projectNumber = 'YOUR_PROJECT_NUMBER';
 * const location = 'YOUR_PROJECT_LOCATION'; // Format is 'us' or 'eu'
 * const userId = 'user:xxx@example.com'; // Format is "user:xxx@example.com"
 */

// Import from google cloud
const {DocumentSchemaServiceClient, DocumentServiceClient} =
  require('@google-cloud/contentwarehouse').v1;

const apiEndpoint =
  location === 'us'
    ? 'contentwarehouse.googleapis.com'
    : `${location}-contentwarehouse.googleapis.com`;

// Create service client
const schemaClient = new DocumentSchemaServiceClient({
  apiEndpoint: apiEndpoint,
});
const serviceClient = new DocumentServiceClient({apiEndpoint: apiEndpoint});

// Get Document Schema
async function quickstart() {
  // The full resource name of the location, e.g.:
  // projects/{project_number}/locations/{location}
  const parent = `projects/${projectNumber}/locations/${location}`;

  // Initialize request argument(s)
  const schemaRequest = {
    parent: parent,
    documentSchema: {
      displayName: 'My Test Schema',
      propertyDefinitions: [
        {
          name: 'testPropertyDefinitionName', // Must be unique within a document schema (case insensitive)
          displayName: 'searchable text',
          isSearchable: true,
          textTypeOptions: {},
        },
      ],
    },
  };

  // Create Document Schema
  const documentSchema =
    await schemaClient.createDocumentSchema(schemaRequest);

  const documentRequest = {
    parent: parent,
    document: {
      displayName: 'My Test Document',
      documentSchemaName: documentSchema[0].name,
      plainText: "This is a sample of a document's text.",
      properties: [
        {
          name: 'testPropertyDefinitionName',
          textValues: {values: ['GOOG']},
        },
      ],
    },
    requestMetadata: {userInfo: {id: userId}},
  };

  // Make Request
  const response = serviceClient.createDocument(documentRequest);

  // Print out response
  response.then(
    result => console.log(`Document Created: ${JSON.stringify(result)}`),
    error => console.log(`error: ${error}`)
  );
}

Python

Pour en savoir plus, consultez la documentation de référence de l'API Document AI Warehouse Python.


from google.cloud import contentwarehouse

# TODO(developer): Uncomment these variables before running the sample.
# project_number = 'YOUR_PROJECT_NUMBER'
# location = 'YOUR_PROJECT_LOCATION' # Format is 'us' or 'eu'
# user_id = "user:xxxx@example.com" # Format is "user:xxxx@example.com"


def quickstart(project_number: str, location: str, user_id: str) -> None:
    # Create a Schema Service client
    document_schema_client = contentwarehouse.DocumentSchemaServiceClient()

    # The full resource name of the location, e.g.:
    # projects/{project_number}/locations/{location}
    parent = document_schema_client.common_location_path(
        project=project_number, location=location
    )

    # Define Schema Property of Text Type
    property_definition = contentwarehouse.PropertyDefinition(
        name="stock_symbol",  # Must be unique within a document schema (case insensitive)
        display_name="Searchable text",
        is_searchable=True,
        text_type_options=contentwarehouse.TextTypeOptions(),
    )

    # Define Document Schema Request
    create_document_schema_request = contentwarehouse.CreateDocumentSchemaRequest(
        parent=parent,
        document_schema=contentwarehouse.DocumentSchema(
            display_name="My Test Schema",
            property_definitions=[property_definition],
        ),
    )

    # Create a Document schema
    document_schema = document_schema_client.create_document_schema(
        request=create_document_schema_request
    )

    # Create a Document Service client
    document_client = contentwarehouse.DocumentServiceClient()

    # The full resource name of the location, e.g.:
    # projects/{project_number}/locations/{location}
    parent = document_client.common_location_path(
        project=project_number, location=location
    )

    # Define Document Property Value
    document_property = contentwarehouse.Property(
        name=document_schema.property_definitions[0].name,
        text_values=contentwarehouse.TextArray(values=["GOOG"]),
    )

    # Define Document
    document = contentwarehouse.Document(
        display_name="My Test Document",
        document_schema_name=document_schema.name,
        plain_text="This is a sample of a document's text.",
        properties=[document_property],
    )

    # Define Request
    create_document_request = contentwarehouse.CreateDocumentRequest(
        parent=parent,
        document=document,
        request_metadata=contentwarehouse.RequestMetadata(
            user_info=contentwarehouse.UserInfo(id=user_id)
        ),
    )

    # Create a Document for the given schema
    response = document_client.create_document(request=create_document_request)

    # Read the output
    print(f"Rule Engine Output: {response.rule_engine_output}")
    print(f"Document Created: {response.document}")

Étapes suivantes

Si vous utilisez l'application Web (aperçu), passez à Administrer l'UI Document AI Warehouse pour configurer l'UI de Document AI Warehouse.
Consultez Gérer le contrôle des accès pour comprendre et configurer le contrôle des accès.
Consultez Gérer les schémas de document pour découvrir comment gérer les schémas de document.
Passez à la section Rechercher dans les documents pour découvrir comment effectuer des recherches dans les documents.

Guide de démarrage rapide Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

À propos de la console Google Cloud

Créer un projet

Activer la facturation

Provisionner et initialiser le service

Procédure de provisionnement

Configurer des autorisations au niveau du projet

Autorisations requises

Projets de LCA de document

Projets d'accès universel

Rôles IAM pour les projets d'accès universel

Configurer le jeton d'accès (pour appeler l'API depuis la ligne de commande)

Utiliser le fichier de clé de compte de service dans votre environnement

Linux ou macOS

Windows

Installer et initialiser Google Cloud CLI (facultatif)

Générer le jeton d'accès

Tester l'appel de l'API Document AI Warehouse

Exemples de code

Java

Node.js

Python

Étapes suivantes

Guide de démarrage rapide