Guida rapida: configura l'API Document AI

Questa guida fornisce tutte le procedure di configurazione necessarie per iniziare a utilizzare Document AI.

Informazioni sulla console Google Cloud

Google Cloud console è un'interfaccia utente web utilizzata per eseguire il provisioning, configurare, gestire e monitorare i sistemi che utilizzano i prodotti Google Cloud . Utilizzi la console Google Cloud per configurare e gestire le risorse Document AI.

Crea un progetto

Per utilizzare i servizi forniti da Google Cloud, devi creare un progetto che organizzi tutte le tue risorse Google Cloud e che sia composto dai seguenti componenti:

• Un insieme di collaboratori
• API abilitate (e altre risorse)
• Strumenti di monitoraggio
• Dati di fatturazione
• Autenticazione e controlli dell'accesso
• Processori Document AI

Puoi creare un progetto o più progetti. Puoi utilizzare i tuoi progetti per organizzare le risorse Google Cloud in una gerarchia delle risorse. Per saperne di più sui progetti, consulta la documentazione di Resource Manager.

Nella console Google Cloud , nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud .

Ruoli richiesti per selezionare o creare un progetto

• Seleziona un progetto: la selezione di un progetto non richiede un ruolo IAM specifico. Puoi selezionare qualsiasi progetto per il quale ti è stato concesso un ruolo.
• Crea un progetto: per creare un progetto, devi disporre del ruolo Autore progetto (roles/resourcemanager.projectCreator), che contiene l'autorizzazione resourcemanager.projects.create. Scopri come concedere i ruoli.

Vai al selettore di progetti

Abilita l'API

Devi abilitare l'API Document AI per il tuo progetto. Per ulteriori informazioni sull'attivazione delle API, consulta la documentazione di Service Usage.

Abilita l'API Document AI.

Ruoli richiesti per abilitare le API

Per abilitare le API, devi disporre del ruolo IAM Amministratore utilizzo dei servizi (roles/serviceusage.serviceUsageAdmin), che include l'autorizzazione serviceusage.services.enable. Scopri come concedere i ruoli.

Abilitare l'API

Abilita fatturazione

Un account di fatturazione definisce chi paga per un determinato insieme di risorse. Gli account di fatturazione possono essere collegati a uno o più progetti. L'utilizzo del progetto viene addebitato all'account di fatturazione collegato. Configuri la fatturazione quando crei un progetto. Per saperne di più, consulta la documentazione sulla fatturazione.

Verifica che la fatturazione sia abilitata per il tuo progetto Google Cloud .

Ottenere i ruoli richiesti

Per ottenere le autorizzazioni necessarie per concedere a un principal l'accesso ai file in Cloud Storage, chiedi all'amministratore di concederti il ruolo IAM Storage Admin (roles/storage.admin) sul bucket. Per saperne di più sulla concessione dei ruoli, consulta Gestisci l'accesso a progetti, cartelle e organizzazioni.

Potresti anche riuscire a ottenere le autorizzazioni richieste tramite i ruoli personalizzati o altri ruoli predefiniti.

Località

Document AI ti offre un certo controllo sul luogo in cui le risorse per il tuo progetto vengono archiviate ed elaborate. In particolare, quando crei un processore, devi scegliere una località in cui archiviare ed elaborare i dati. Per impostazione predefinita, Document AI archivia ed elabora le risorse in una località degli Stati Uniti. Se scegli la località Unione Europea, i tuoi dati e processi vengono archiviati solo nell'Unione Europea.

Nota: tu e i tuoi utenti potete accedere ai dati da qualsiasi posizione.

Impostazione della posizione tramite l'API

Devi specificare la posizione del processore ogni volta che invii una richiesta di elaborazione utilizzando l'API. Ad esempio, se il tuo responsabile del trattamento è configurato per archiviare e trattare i tuoi dati nell'Unione Europea, utilizza l'URI eu-documentai.googleapis.com nel seguente modo:

Process	https://eu-documentai.googleapis.com/v1/projects/$PROJECT_ID/locations/eu/processors/$PROCESSOR_ID:process https://eu-documentai.googleapis.com/v1beta3/projects/$PROJECT_ID/locations/eu/processors/$PROCESSOR_ID:process
batchProcess	https://eu-documentai.googleapis.com/v1/projects/$PROJECT_ID/locations/eu/processors/$PROCESSOR_ID:batchProcess https://eu-documentai.googleapis.com/v1beta3/projects/$PROJECT_ID/locations/eu/processors/$PROCESSOR_ID:batchProcess

Installa la libreria client dell'API Document AI

Hai tre opzioni per chiamare l'API Document AI:

• Librerie client supportate da Google (consigliate)
• REST
• gRPC

Le librerie client sono disponibili per diversi linguaggi di programmazione più diffusi. Per informazioni sull'installazione delle librerie client, consulta Librerie client dell'API Document AI.

Installa e inizializza Google Cloud CLI

La CLI gcloud fornisce un insieme di strumenti che puoi utilizzare per gestire le risorse e le applicazioni ospitate su Google Cloud.

Il seguente link fornisce le istruzioni:

Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il comando seguente:

gcloud init

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Configura l'autenticazione

Qualsiasi applicazione client che utilizza l'API deve essere autenticata e deve disporre dell'accesso alle risorse richieste. La configurazione dell'autenticazione dipende dal fatto che tu stia lavorando in un ambiente di sviluppo locale o configurando un ambiente di produzione. Per saperne di più, consulta Configura le credenziali predefinite dell'applicazione.

Seleziona le schede relative alla modalità di accesso all'API:

gcloud

Installa Google Cloud CLI. Dopo l'installazione, inizializza Google Cloud CLI eseguendo il comando seguente:

gcloud init

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Librerie client

Per utilizzare le librerie client in un ambiente di sviluppo locale, installa e inizializza gcloud CLI, quindi configura Credenziali predefinite dell'applicazione con le tue credenziali utente.

1. Installa Google Cloud CLI.

2. Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

3. Se utilizzi una shell locale, crea le credenziali di autenticazione locali per il tuo account utente:

   gcloud auth application-default login

   Non è necessario eseguire questa operazione se utilizzi Cloud Shell.

   Se viene restituito un errore di autenticazione e utilizzi un provider di identità (IdP) esterno, verifica di aver acceduto a gcloud CLI con la tua identità federata.

Per saperne di più, consulta Configura ADC per un ambiente di sviluppo locale nella documentazione sull'autenticazione di Google Cloud .

REST

Per utilizzare l'API REST in un ambiente di sviluppo locale, utilizzi le credenziali che fornisci a gcloud CLI.

Installa Google Cloud CLI.

Se utilizzi un provider di identità (IdP) esterno, devi prima accedere a gcloud CLI con la tua identità federata.

Per saperne di più, consulta Autenticati per usare REST nella documentazione sull'autenticazione di Google Cloud .

Per informazioni sulla configurazione dell'autenticazione per un ambiente di produzione, consulta Configura le Credenziali predefinite dell'applicazione per il codice in esecuzione su Google Cloud nella documentazione sull'autenticazione di Google Cloud .

Informazioni sui ruoli

Quando un'entità autenticata tenta di accedere a una risorsa, IAM verifica se l'entità dispone delle autorizzazioni richieste. Google CloudConcedi le autorizzazioni alle entità assegnando ruoli nelle policy di autorizzazione IAM. Per saperne di più su entità, ruoli, risorse e policy di autorizzazione, consulta la panoramica di IAM.

Segui il principio del privilegio minimo quando concedi ruoli sulle risorseGoogle Cloud alle entità. Non concedere a un principal più autorizzazioni di quelle necessarie per completare la richiesta. Per ulteriori informazioni sulle best practice per controllo dell'accesso, consulta Utilizzare IAM in modo sicuro.

Per accedere alle risorse in Document AI, utilizza un ruolo che disponga delle autorizzazioni specifiche necessarie. Per saperne di più, consulta Autorizzazioni Document AI e Ruoli Document AI.

Configurazione dell'accesso ai file tra progetti

Quando configuri il processore Document AI in un progetto, potresti voler che questo progetto acceda ai file di input archiviati in un progetto diverso della stessa organizzazione che ospita i processori Document AI.

Per consentire l'accesso tra progetti, devi concedere il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer) all'agente di servizio Document AI, come mostrato nella figura seguente.

Esempio

• Supponiamo che il progetto A ospiti i processori Document AI e, facoltativamente, un bucket in cui viene scritto l'output del processore.
• Project B è proprietario del bucket che contiene i file di input per i processori Document AI.

• Per rendere accessibili i file nel progetto B al progetto A, devi concedere il ruolo Visualizzatore oggetti Storage (roles/storage.objectViewer) per il bucket di input nel progetto B al service agent Document AI del progetto A.

  

Per saperne di più su IAM e sul ruolo Visualizzatore oggetti Storage, consulta Ruoli IAM per Cloud Storage.

Service account integrati

Un service agent Document AI segue questa convenzione di denominazione:

service-{project number}@gcp-sa-prod-dai-core.iam.gserviceaccount.com

Esempio: [e-mail]

Passaggi successivi: casi d'uso

Dopo aver attivato l'API Document AI, è possibile creare e utilizzare i processori Document AI. Il tipo di processore migliore dipende dal tuo caso d'uso.