快速入门

本指南介绍了开始使用 Document AI Warehouse 所需的所有设置步骤。

Google Cloud 控制台简介

Google Cloud console 是一个网页界面，用于预配、配置、管理和监控使用 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 Admin 和 Service Usage Admin 角色。

预配步骤

选择一个区域。

在配置页面上，选择要启用的区域。

每个区域都是独立的。因此，如果您想使用多个区域，请分别预配每个区域。
启用核心 API。{:#enable-core-api}:

点击启用。这会在您的项目中启用 Document AI Warehouse 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 界面支持	是	否	可以（如果用户拥有项目级访问权限）

启用提问和回答功能：

如果您想在项目中启用生成式 AI 搜索，请选中问答。如需了解详情（包括如何将自己列入许可名单以使用该功能），请参阅生成式 AI 搜索。

触发配置：

点击预配以开始预配项目。设置实例需要一段时间（3-5 分钟）。
创建默认架构。

在初始化步骤中，点击创建。这会创建一个可用于 OCR 提取的 PDF 或 TXT 文件的默认架构。它包含用于编制索引的原始文本字段，但不包含属性。
查看实例：

这样一来，您的配置流程就完成了。如果您的项目使用文档级访问权限控制，请继续前往下一部分，以设置项目级权限。

如果您已加入 Google Cloud 控制台界面功能的许可名单，则可以点击开始使用，开始在 Google Cloud 控制台中使用 Document AI Warehouse。

如果您不在 Google Cloud 控制台界面功能的许可名单中，可以继续配置 Web 应用，了解如何设置 Document AI Warehouse Web 应用。
在 IAM 中为用户配置所需权限。如果启用了文档级访问权限控制，则需要项目级权限和 IAM 权限。如需了解详情，请参阅所需权限。

设置项目级权限

如果您的项目启用了文档级访问权限控制（ACL 模式选择中的选项 1），则必须向管理员账号以及用户授予项目级权限。

为此，请在完成配置后的最终视图中前往项目权限：

请按照以下步骤将您的管理员账号添加为文档管理员：

点击添加用户
输入管理员的电子邮件地址，然后选择文档管理员作为访问权限级别。点击保存。
对于其他用户，您可以将其添加为：
1. Document Admin：一种角色，可完全访问项目中的所有文档，包括上传文档以及查看/修改/删除所有文档，无论文档所有者是谁。此外，文档管理员还可以更改所有文档的权限。
2. 文档编辑者：一种角色，拥有查看和修改所有文档的权限，但无法在项目中创建和删除文档，也无法更改文档的权限。
3. Document Viewer：一种仅具有查看所有文档的权限的角色。文档查看者无法创建、修改、删除文档或更改文档的权限。
4. Document Creator：仅具有文档上传权限的角色。文档创建者对其上传的文档拥有完整权限，但除非获得明确的权限，否则对任何其他文档都没有任何其他权限。
该电子邮件可以是单个用户的电子邮件地址，也可以是群组的电子邮件地址。指定群组电子邮件时，请在类型字段中选择群组。

注意： Document AI Warehouse 不支持子群组访问权限扩展。如果权限是授予群组的，则用户必须是群组中的直接子级。

所需权限

在 Document AI Warehouse 中，我们在 IAM 的基础上构建了一个独立的 ACL 系统。对于文档级 ACL 项目，您需要在 Document AI Warehouse 的 ACL 系统中获取额外的项目级权限。对于通用访问项目，只需要 IAM 权限。

下表总结了所需的权限：

文档 ACL 项目

用户类型	IAM 角色	Document AI Warehouse 的项目级权限
管理员用户	Content Warehouse Admin	Document Admin
普通用户	Content Warehouse Document Schema Viewer	文档创建者/编辑者/Viewer，具体取决于预期权限

通用访问项目

用户类型	IAM 角色
管理员用户	1. Content Warehouse Admin 2. Content Warehouse 文档管理员
普通用户	1. Content Warehouse document Schema Viewer 2. Content Warehouse 文档创建者/查看者/编辑器，具体取决于预期权限

通用访问权限项目的 IAM 角色

角色名称	角色名称	用途
Content Warehouse document creator	`contentwarehouse.documentCreator`	创建文档
Content Warehouse 文档查看器	`contentwarehouse.documentViewer`	查看任何文档
Content Warehouse Document Editor	`contentwarehouse.documentEditor`	修改任何文档（不包括创建和删除）
Content Warehouse 文档管理员	`contentwarehouse.documentAdmin`	管理任何文档（包括创建和删除）
Content Warehouse Admin	`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}")

后续步骤

如果您使用的是 Web 应用（预览版），请继续管理 Document AI Warehouse 界面，以设置 Document AI Warehouse 的界面。
请继续参阅管理访问权限控制，了解并配置访问权限控制。
请继续参阅管理文档架构，了解如何管理文档架构。
请继续前往搜索文档，了解如何搜索文档。

快速入门 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

Google Cloud 控制台简介

创建项目

启用结算功能

预配和初始化服务

预配步骤

设置项目级权限

所需权限

文档 ACL 项目

通用访问项目

通用访问权限项目的 IAM 角色

设置访问令牌（用于通过命令行调用 API）

在您的环境中使用服务账号密钥文件

Linux 或 macOS

Windows

安装并初始化 Google Cloud CLI（可选）

生成访问令牌

测试调用 Document AI Warehouse API

代码示例

Java

Node.js

Python

后续步骤

快速入门