Panduan memulai

Panduan ini menyediakan semua langkah penyiapan yang diperlukan untuk mulai menggunakan Document AI Warehouse.

Tentang konsol Google Cloud

Google Cloud console adalah UI web yang digunakan untuk menyediakan, mengonfigurasi, mengelola, dan memantau sistem yang menggunakan produk Google Cloud . Anda dapat menggunakan konsolGoogle Cloud untuk menyiapkan dan mengelola resource Document AI Warehouse.

Membuat project

Untuk menggunakan layanan yang disediakan oleh Google Cloud, Anda harus membuat project.

Project akan mengorganisasikan semua resource Google Cloud Anda. Project terdiri dari komponen berikut:

  • Sekumpulan kolaborator
  • API yang diaktifkan (dan resource lainnya)
  • Alat pemantauan
  • Informasi penagihan
  • Autentikasi dan kontrol akses

Anda dapat membuat satu project, atau membuat beberapa project. Anda dapat menggunakan project untuk mengatur resource Google Cloud dalam hierarki resource. Untuk mengetahui informasi selengkapnya tentang project, lihat dokumentasi 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

Aktifkan penagihan

Akun penagihan menentukan siapa yang membayar serangkaian resource tertentu. Akun penagihan dapat ditautkan ke satu atau beberapa project. Penggunaan project ditagihkan ke akun penagihan tertaut. Anda dapat mengonfigurasi penagihan saat membuat project. Untuk mengetahui informasi selengkapnya, lihat dokumentasi Penagihan.

Verify that billing is enabled for your Google Cloud project.

Menyediakan dan melakukan inisialisasi layanan

Sebelum menggunakan Document AI Warehouse untuk pertama kalinya, Anda harus menyediakan dan menginisialisasi resource yang terkait dengan project Anda di halaman Penyediaan Document AI Warehouse.

Jika Anda ingin menyediakan resource, Anda harus diberi peran Admin Content Warehouse dan Admin Penggunaan Layanan project.

Langkah-langkah penyediaan

  1. Pilih region.

    Di halaman penyediaan, pilih region yang ingin Anda aktifkan.

    Setiap wilayah bersifat independen. Oleh karena itu, jika Anda ingin menggunakan lebih dari satu region, sediakan setiap region secara terpisah.

  2. Aktifkan API inti. {:#enable-core-api}:

    Klik Enable. Tindakan ini akan mengaktifkan Document AI Warehouse API di project Anda.

    Setelah API diaktifkan, klik Next.

  3. Sediakan instance.

    Langkah ini menyediakan resource untuk project Anda di layanan Document AI Warehouse. Anda harus memilih salah satu dari tiga mode kontrol akses. Tinjau dengan cermat untuk memilih mode yang tepat untuk kasus penggunaan Anda. Untuk mengetahui informasi selengkapnya, lihat halaman mode kontrol akses.

    1. Pilih mode kontrol akses (ACL).

      • [Direkomendasikan] Kontrol akses tingkat dokumen dengan pengguna di Cloud Identity.

        Hal ini berlaku jika organisasi Anda mengelola pengguna atau grup di layanan Cloud Identity.

      • Kontrol akses tingkat dokumen dengan pengguna di kontrol akses layanan Bring-your-own Identity.

        Jika pengguna Anda tidak dapat ditambahkan atau disinkronkan ke Cloud Identity, gunakan mode ini. Namun:

        • Antarmuka Document AI Warehouse tidak mendukung mode ini; aplikasi klien kustom mungkin diperlukan.
        • Aplikasi klien kustom Anda mengautentikasi pengguna terhadap penyedia identitas dan meneruskan keanggotaan pengguna dan grup menggunakan Document AI Warehouse API.
      • Akses universal: Tidak ada kontrol akses tingkat dokumen.

        • Antarmuka Document AI Warehouse mendukung mode ini untuk mengautentikasi pengguna.
        • Mode ini biasanya digunakan untuk memberikan akses kepada pengguna publik tanpa memerlukan autentikasi.
        • Portal kustom dapat mengakses semua dokumen menggunakan akun layanan dengan peran yang diinginkan (misalnya, peran Pelihat Dokumen) dan dapat meneruskan akses ini kepada pengguna publik tanpa autentikasi.
      Kontrol akses tingkat dokumen dengan pengguna di Cloud Identity Kontrol akses tingkat dokumen dengan pengguna di layanan kontrol akses Bring-your-own Identity Akses universal
      Akses tingkat dokumen Ya Ya Tidak
      Dukungan UI Document AI Warehouse Ya Tidak Ya (jika pengguna memiliki akses tingkat project)

    2. Mengaktifkan tanya jawab:

      Centang Tanya Jawab jika Anda ingin mengaktifkan penelusuran GenAI di project Anda. Lihat Penelusuran AI Generatif untuk mengetahui informasi selengkapnya, termasuk cara mendapatkan izin untuk menggunakan fitur ini.

  4. Memicu penyediaan:

    Klik Provision untuk mulai menyediakan project Anda. Penyiapan instance akan memerlukan waktu beberapa saat (3-5 menit).

  5. Buat skema default.

    Klik Create di langkah inisialisasi. Tindakan ini akan membuat skema default yang dapat digunakan untuk PDF atau file TXT yang diekstrak OCR. Objek ini berisi kolom teks mentah untuk pengindeksan, tetapi tidak berisi properti.

  6. Lihat instance:

    Tindakan ini akan menyelesaikan proses penyediaan Anda. Jika project Anda menggunakan kontrol akses tingkat dokumen, lanjutkan ke bagian berikutnya untuk menyiapkan izin tingkat project.

    Jika Anda berada dalam daftar yang diizinkan untuk Google Cloud fitur UI konsol, Anda dapat mengklik Mulai untuk mulai menggunakan Document AI Warehouse di konsol Google Cloud .

    Jika Anda tidak termasuk dalam daftar yang diizinkan untuk menggunakan fitur UI konsol, Anda dapat melanjutkan untuk mengonfigurasi aplikasi web guna mempelajari cara menyiapkan aplikasi web Document AI Warehouse. Google Cloud

  7. Konfigurasi izin yang diperlukan di IAM untuk pengguna Anda. Jika kontrol akses tingkat dokumen diaktifkan, izin tingkat project dan izin IAM diperlukan. Lihat izin yang diperlukan untuk detail selengkapnya.

Menyiapkan izin tingkat project

Jika project Anda mengaktifkan kontrol akses tingkat dokumen (Opsi 1 dalam pemilihan mode ACL), Anda harus memberikan izin tingkat project kepada akun administrator dan pengguna Anda.

Untuk melakukannya, di tampilan akhir setelah penyediaan, buka Izin Project:

Ikuti langkah-langkah di bawah untuk menambahkan akun admin Anda sebagai Admin Dokumen:

  1. Klik Tambahkan Pengguna

  2. Masukkan email admin Anda, lalu pilih Admin Dokumen sebagai tingkat aksesnya. Klik Simpan.

  3. Untuk pengguna lain, Anda dapat menambahkannya sebagai:

    1. Admin Dokumen: Peran dengan akses penuh ke semua dokumen dalam project, termasuk mengupload dokumen dan melihat/mengedit/menghapus semua dokumen, terlepas dari pemilik dokumen. Selain itu, admin dokumen dapat mengubah izin semua dokumen.

    2. Editor Dokumen: Peran dengan izin melihat dan mengedit semua dokumen, tetapi tidak dapat membuat dan menghapus dokumen dalam project dan tidak dapat mengubah izin dokumen.

    3. Pelihat Dokumen: Peran dengan hanya izin melihat semua dokumen. Pelihat dokumen tidak dapat membuat, mengedit, menghapus, atau mengubah izin dokumen.

    4. Pembuat Dokumen: Peran dengan izin hanya untuk mengupload dokumen. Pembuat dokumen memiliki izin penuh untuk dokumen yang mereka upload, tetapi tidak memiliki izin lain untuk dokumen lain kecuali mereka mendapatkan izin eksplisit untuk dokumen tersebut.

  4. Email dapat berupa email pengguna tunggal atau email grup. Pilih Grup di kolom Jenis saat menentukan email grup.

Izin yang diperlukan

Di Document AI Warehouse, kami memiliki sistem ACL independen di atas IAM. Untuk project ACL tingkat dokumen, Anda harus mendapatkan izin tingkat project tambahan di sistem ACL Document AI Warehouse. Untuk project akses universal, hanya izin IAM yang diperlukan.

Berikut adalah tabel ringkasan untuk izin yang diperlukan:

Project Document-ACL

Jenis pengguna Peran IAM Izin tingkat project Document AI Warehouse
Pengguna admin Admin Content Warehouse Admin Dokumen
Pengguna normal Penampil Skema dokumen Content Warehouse Pembuat/Editor/Pelihat Dokumen, bergantung pada izin yang diinginkan

Project akses universal

Jenis pengguna Peran IAM
Pengguna admin 1. Admin Content Warehouse
2. Admin dokumen Content Warehouse
Pengguna normal 1. Penampil Skema dokumen Content Warehouse
2. Pembuat/pelihat/editor dokumen Content Warehouse, bergantung pada izin yang diinginkan
Peran IAM untuk project akses universal
Nama Peran Nama peran Tujuan
Pembuat dokumen Content Warehouse contentwarehouse.documentCreator Membuat dokumen
Penampil dokumen Content Warehouse contentwarehouse.documentViewer Melihat dokumen apa pun
Editor dokumen Content Warehouse contentwarehouse.documentEditor Mengedit dokumen apa pun (tidak termasuk membuat dan menghapus)
Admin dokumen Content Warehouse contentwarehouse.documentAdmin Mengelola dokumen apa pun (termasuk membuat dan menghapus)
Admin Content Warehouse contentwarehouse.admin Mengelola dokumen, serta skema dan aturan

Lihat Peran dan izin IAM untuk mengetahui detail selengkapnya.

Menyiapkan token akses (untuk memanggil API dari command line)

Untuk memanggil Document AI Warehouse API dengan alat command line, ikuti langkah-langkah berikut.

Menggunakan file kunci akun layanan di lingkungan Anda

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

Instal dan lakukan inisialisasi Google Cloud CLI (opsional)

gcloud CLI menyediakan serangkaian alat yang dapat Anda gunakan untuk mengelola resource dan aplikasi yang dihosting di Google Cloud.

Link berikut berisi petunjuk:

Instal Google Cloud CLI. Setelah penginstalan, inisialisasi Google Cloud CLI dengan menjalankan perintah berikut:

gcloud init

Jika Anda menggunakan penyedia identitas (IdP) eksternal, Anda harus login ke gcloud CLI dengan identitas gabungan Anda terlebih dahulu.

Membuat token akses

Jika di langkah sebelumnya Anda telah menyiapkan autentikasi, Anda dapat menggunakan Google Cloud CLI untuk menguji lingkungan autentikasi Anda. Jalankan perintah berikut dan pastikan tidak ada error yang terjadi dan kredensial ditampilkan:

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

Pastikan AUTH_TOKEN ditetapkan, misalnya:

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

Menguji panggilan Document AI Warehouse API

AUTH_TOKEN digunakan oleh semua contoh REST Document AI Warehouse API untuk mengautentikasi panggilan API. Misalnya, perintah berikut mengambil semua skema dokumen yang Anda tentukan yang terkait dengan project Anda (untuk sebagian besar kasus, gunakan "us" sebagai lokasi):

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

Contoh Kode

Java

Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Java Document AI Warehouse.

Untuk melakukan autentikasi ke Document AI Warehouse, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Node.js Document AI Warehouse.

Untuk melakukan autentikasi ke Document AI Warehouse, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.

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

Untuk mengetahui informasi selengkapnya, lihat dokumentasi referensi API Python Document AI Warehouse.

Untuk melakukan autentikasi ke Document AI Warehouse, siapkan Kredensial Default Aplikasi. Untuk mengetahui informasi selengkapnya, lihat Menyiapkan autentikasi untuk lingkungan pengembangan lokal.


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

Langkah berikutnya