快速入門導覽課程

本指南提供開始使用 Document AI 倉儲的所有必要設定步驟。

關於 Google Cloud 控制台

Google Cloud console 是一個網頁版 UI，可用於佈建、設定、管理和監控使用 Google Cloud 產品的系統。您可以使用Google Cloud 控制台設定及管理 Document AI Warehouse 資源。

建立專案

如要使用 Google Cloud提供的服務，必須建立專案。

專案可整理您所有 Google Cloud 資源。專案包含下列元件：

一組協作者
已啟用的 API (和其他資源)
監控工具
帳單資訊
驗證和存取權控管

您可以建立一個或多個專案。您可以使用專案，在資源階層中整理 Google Cloud 資源。如要進一步瞭解專案，請參閱 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

啟用計費功能

帳單帳戶會定義特定資源組合的費用由誰支付。帳單帳戶可連結至一或多項專案，專案的使用費會從相連結的帳單帳戶中扣除。您可以在建立專案時設定帳單。詳情請參閱帳單說明文件。

Verify that billing is enabled for your Google Cloud project.

佈建及初始化服務

首次使用 Document AI Warehouse 前，請先在Document AI Warehouse 資源佈建頁面上，佈建及初始化與專案相關聯的資源。

如要佈建資源，您必須具備專案的「Content Warehouse 管理員」和「服務使用情形管理員」角色。

佈建步驟

選擇區域。

在佈建頁面中，選取要啟用的區域。

每個區域都是獨立的。因此，如要使用多個區域，請分別佈建每個區域。
啟用核心 API。{:#enable-core-api}:

按一下「啟用」。這會在專案中啟用 Document AI 倉儲 API。

啟用 API 後，按一下「下一步」。

佈建執行個體。

這個步驟會在 Document AI Warehouse 服務中，為專案佈建資源。您必須從三種存取控管模式中選擇。請仔細查看這些模式，然後根據用途選取合適的模式。詳情請參閱存取權控管模式頁面。

選取存取控制清單 (ACL) 模式。

[建議] 在 Cloud Identity 對使用者設定文件層級的存取控管機制。

如果貴機構透過 Cloud Identity 服務管理使用者或群組，就適用這個模式。
- Document AI Warehouse 介面支援這個模式，可驗證使用者身分。
- 貴機構的 LDAP 和 Active Directory 使用者和群組可以同步至 Cloud Identity。
- 您可以輕鬆將 Google Workspace 使用者新增至 Cloud Identity。
透過「自備身分」服務，對使用者設定文件層級的存取控管機制。

如果無法將使用者新增或同步至 Cloud Identity，請採用這個模式。不受影響：
- Document AI Warehouse 介面不支援這個模式，因此可能需要自訂用戶端應用程式。
- 自訂用戶端應用程式會向身分識別提供者驗證使用者的身分，並透過 Document AI Warehouse API 傳遞使用者和群組成員身分。
通用存取權：不設定文件層級的存取控管機制。
- Document AI Warehouse 介面支援這個模式，可驗證使用者身分。
- 通常會使用這個模式，將存取權授予大眾使用者，不需要驗證身分。
- 自訂入口網站可以透過具備所需角色 (例如「Document Viewer」) 的服務帳戶存取所有文件，並將這項存取權轉發給大眾使用者，無須進行驗證。

	在 Cloud Identity 對使用者設定文件層級的存取控管機制	透過「自備身分」服務，對使用者設定文件層級的存取控管機制	通用存取權
文件層級存取權	是	是	否
Document AI Warehouse UI 支援	是	否	是 (如果使用者具有專案層級存取權)

啟用問答功能：

如要在專案中啟用生成式 AI 搜尋功能，請勾選「問答」。如要進一步瞭解生成式 AI 搜尋，包括如何加入允許清單來使用這項功能，請參閱這篇文章。

觸發布建程序：

按一下「佈建」，開始佈建專案。設定執行個體需要一段時間 (3 到 5 分鐘)。
建立預設結構定義。

在初始化步驟中，按一下「建立」。這會建立預設結構定義，可用於 OCR 擷取的 PDF 或 TXT 檔案。其中包含用於建立索引的原始文字欄位，但不含屬性。
查看執行個體：

這樣就完成佈建程序。如果專案使用文件層級存取權控管，請前往下一節設定專案層級權限。

如果您已加入 Google Cloud 控制台 UI 功能的允許清單，可以點按「開始使用」，在 Google Cloud 控制台中開始使用 Document AI 倉儲。

如果您不在 Google Cloud 控制台 UI 功能的允許清單中，可以繼續設定網頁應用程式，瞭解如何設定 Document AI Warehouse 網頁應用程式。
在 IAM 中為使用者設定必要權限。如果啟用文件層級的存取控管機制，則必須具備專案層級的權限和 IAM 權限。詳情請參閱必要權限。

設定專案層級權限

如果專案啟用文件層級存取權控管 (「ACL 模式選取」中的選項 1)，您必須授予管理員帳戶和使用者專案層級權限。

如要這麼做，請在佈建後的最終檢視畫面中，前往「專案權限」：

請按照下列步驟，將管理員帳戶新增為文件管理員：

按一下「新增使用者」
輸入管理員的電子郵件地址，然後選擇「文件管理員」做為存取層級。然後按一下 [儲存]。
如要新增其他使用者，可以將他們設為：
1. 文件管理員：這個角色可完全存取專案中的所有文件，包括上傳文件，以及查看/編輯/刪除所有文件 (無論文件擁有者是誰)。此外，文件管理員可以變更所有文件的權限。
2. 文件編輯者：這個角色具備查看及編輯所有文件的權限，但無法在專案中建立及刪除文件，也無法變更文件的權限。
3. 文件檢視者：這個角色只有權限檢視所有文件，文件檢視者無法建立、編輯、刪除文件或變更文件權限。
4. 文件建立者：這個角色只有上傳文件的權限。文件建立者對自己上傳的文件擁有完整權限，但除非獲得明確授權，否則對其他文件沒有任何權限。
電子郵件可以是單一使用者或群組的電子郵件地址。指定群組電子郵件時，請在「類型」欄位中選擇「群組」。

注意： Document AI Warehouse 不支援擴充子群組存取權。如果權限是授予群組，使用者必須是群組中的直接子項。

所需權限

在 Document AI 倉儲中，我們在 IAM 基礎上建構了獨立的 ACL 系統。如果是文件層級 ACL 專案，您需要在 Document AI Warehouse 的 ACL 系統中取得額外的專案層級權限。如果是通用存取專案，只需要身分與存取權管理權限。

下表摘要列出必要權限：

Document-ACL 專案

使用者類型	IAM 角色	Document AI 倉儲的專案層級權限
管理員使用者	內容倉儲管理員	文件管理員
一般使用者	內容倉儲文件結構定義檢視者	文件建立者/編輯者/檢視者，視所需權限而定

通用存取專案

使用者類型	IAM 角色
管理員使用者	1. 內容倉儲管理員 2. 內容倉儲文件管理員
一般使用者	1. 內容倉儲文件結構定義檢視器 2. 內容倉儲文件建立者/檢視者/編輯者，視所需權限而定

通用存取專案的 IAM 角色

角色稱號	角色名稱	目的
內容倉儲文件建立者	`contentwarehouse.documentCreator`	建立文件
內容倉儲文件檢視者	`contentwarehouse.documentViewer`	查看任何文件
內容倉儲文件編輯者	`contentwarehouse.documentEditor`	編輯任何文件 (不包括建立和刪除)
內容倉儲文件管理員	`contentwarehouse.documentAdmin`	管理任何文件 (包括建立及刪除)
內容倉儲管理員	`contentwarehouse.admin`	管理任何文件、結構定義和規則

詳情請參閱「IAM 角色和權限」。

設定存取權杖 (透過指令列呼叫 API 時使用)

如要使用指令列工具呼叫 Document AI Warehouse API，請按照下列步驟操作。

在您的環境中使用服務帳戶金鑰檔案

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 或 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.

安裝及初始化 Google Cloud CLI (選用)

gcloud CLI 提供一套工具，可用來管理託管於 Google Cloud的資源和應用程式。

以下連結提供操作說明：

安裝 Google Cloud CLI。完成後，執行下列指令來初始化 Google Cloud CLI：

gcloud init

若您採用的是外部識別資訊提供者 (IdP)，請先使用聯合身分登入 gcloud CLI。

產生存取權杖

如果您已在先前的步驟中設定驗證，可以使用 Google Cloud CLI 測試驗證環境。執行下列指令，並確認沒有發生任何錯誤，且會傳回憑證：

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

預期會設定 AUTH_TOKEN，例如：

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

測試呼叫 Document AI Warehouse API

所有 Document AI Warehouse API REST 範例都會使用 AUTH_TOKEN 來驗證 API 呼叫。舉例來說，下列指令會擷取您定義的所有文件結構定義，這些結構定義與您的專案相關聯 (在大多數情況下，請使用「us」做為位置)：

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

程式碼範例

Java

詳情請參閱 Document AI Warehouse Java API 參考文件。

如要向 Document AI Warehouse 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

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

詳情請參閱 Document AI Warehouse Node.js API 參考文件。

如要向 Document AI Warehouse 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。

/**
 * 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

詳情請參閱 Document AI Warehouse Python API 參考文件。

如要向 Document AI Warehouse 進行驗證，請設定應用程式預設憑證。詳情請參閱「為本機開發環境設定驗證機制」。


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}")

後續步驟

如果您使用網頁應用程式 (預先發布版)，請前往「管理 Document AI 倉儲使用者介面」，設定 Document AI 倉儲使用者介面。
請前往「管理存取權控管」，瞭解及設定存取權控管。
請參閱「管理文件結構定義」，瞭解如何管理文件結構定義。
請參閱「搜尋文件」一節，瞭解如何搜尋文件。

快速入門導覽課程 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

關於 Google Cloud 控制台

建立專案

啟用計費功能

佈建及初始化服務

佈建步驟

設定專案層級權限

所需權限

Document-ACL 專案

通用存取專案

通用存取專案的 IAM 角色

設定存取權杖 (透過指令列呼叫 API 時使用)

在您的環境中使用服務帳戶金鑰檔案

Linux 或 macOS

Windows

安裝及初始化 Google Cloud CLI (選用)

產生存取權杖

測試呼叫 Document AI Warehouse API

程式碼範例

Java

Node.js

Python

後續步驟

快速入門導覽課程