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 Google Cloud konsol 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.

Di konsol Google Cloud , pada halaman pemilih project, pilih atau buat project Google Cloud .

Peran yang diperlukan untuk memilih atau membuat project

Pilih project: Memilih project tidak memerlukan peran IAM tertentu—Anda dapat memilih project mana pun yang telah diberi peran.
Membuat project: Untuk membuat project, Anda memerlukan peran Pembuat Project (roles/resourcemanager.projectCreator), yang berisi izin resourcemanager.projects.create. Pelajari cara memberikan peran.

Buka pemilih project

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.

Verifikasi bahwa penagihan diaktifkan untuk project Google Cloud Anda.

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 ingin menyediakan resource, Anda harus diberi peran Admin Content Warehouse dan Admin Penggunaan Layanan project.

Langkah-langkah penyediaan

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.
Aktifkan API inti. {:#enable-core-api}:

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

Setelah API diaktifkan, klik Next.

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.

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.
- Antarmuka Document AI Warehouse mendukung mode ini untuk mengautentikasi pengguna.
- Pengguna dan grup LDAP dan Active Directory organisasi Anda dapat disinkronkan ke Cloud Identity.
- Pengguna Google Workspace dapat ditambahkan dengan mudah ke Cloud Identity.
Kontrol akses tingkat dokumen dengan pengguna di kontrol akses layanan Identity milik Anda.

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 kontrol akses layanan 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)

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 masuk dalam daftar yang diizinkan untuk menggunakan fitur ini.

Memicu penyediaan:

Klik Provision untuk mulai menyediakan project Anda. Penyiapan instance akan memerlukan waktu beberapa saat (3-5 menit).
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.
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 fitur UI konsol, Anda dapat melanjutkan untuk mengonfigurasi aplikasi web guna mempelajari cara menyiapkan aplikasi web Document AI Warehouse. Google Cloud
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:

Klik Tambahkan Pengguna
Masukkan email admin Anda, lalu pilih Admin Dokumen sebagai tingkat aksesnya. Klik Simpan.
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 hanya izin 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.
Email dapat berupa email pengguna tunggal atau email grup. Pilih Grup di kolom Jenis saat menentukan email grup.

Catatan: Document AI Warehouse tidak mendukung perluasan akses subgrup. Jika izin diberikan kepada grup, pengguna harus menjadi turunan langsung dalam grup.

Izin yang diperlukan

Di Document AI Warehouse, kami memiliki sistem ACL independen di atas IAM. Untuk project ACL tingkat dokumen, Anda perlu 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

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 telah 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 Java API 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 Node.js API 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 Python API 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

Jika Anda menggunakan aplikasi web (pratinjau), lanjutkan ke Mengelola UI Document AI Warehouse untuk menyiapkan UI untuk Document AI Warehouse.
Lanjutkan ke Mengelola kontrol akses untuk memahami dan mengonfigurasi kontrol akses.
Lanjutkan ke Mengelola skema dokumen untuk mempelajari cara mengelola skema dokumen.
Lanjutkan ke Menelusuri dokumen untuk mempelajari cara menelusuri dokumen.

Panduan memulai Tetap teratur dengan koleksi Simpan dan kategorikan konten berdasarkan preferensi Anda.

Tentang konsol Google Cloud

Membuat project

Aktifkan penagihan

Menyediakan dan melakukan inisialisasi layanan

Langkah-langkah penyediaan

Menyiapkan izin tingkat project

Izin yang diperlukan

Project Document-ACL

Project akses universal

Peran IAM untuk project akses universal

Menyiapkan token akses (untuk memanggil API dari command line)

Menggunakan file kunci akun layanan di lingkungan Anda

Instal dan lakukan inisialisasi Google Cloud CLI (opsional)

Membuat token akses

Menguji panggilan Document AI Warehouse API

Contoh Kode

Java

Node.js

Python

Langkah berikutnya

Panduan memulai