Template Teks Cloud Storage ke Spanner

Template Cloud Storage Text to Spanner adalah pipeline batch yang membaca file teks CSV dari Cloud Storage dan mengimpornya ke database Spanner.

Persyaratan pipeline

• Database dan tabel Spanner target harus ada.
• Anda harus memiliki izin baca untuk bucket Cloud Storage dan izin tulis untuk database Spanner target.
• Jalur Cloud Storage input yang berisi file CSV harus ada.
• Anda harus membuat file manifes impor yang berisi deskripsi JSON dari file CSV, dan Anda harus menyimpan file manifes tersebut di Cloud Storage.
• Jika database Spanner target sudah memiliki skema, setiap kolom yang ditentukan dalam file manifes harus memiliki jenis data yang sama dengan kolom terkait dalam skema database target.

• File manifes, yang dienkode dalam ASCII atau UTF-8, harus cocok dengan format berikut:

  Format dan contoh manifes

  Format file manifes sesuai dengan jenis pesan berikut, yang ditampilkan di sini dalam format protocol buffer:

  message ImportManifest {
    // The per-table import manifest.
    message TableManifest {
      // Required. The name of the destination table.
      string table_name = 1;
      // Required. The CSV files to import. This value can be either a filepath or a glob pattern.
      repeated string file_patterns = 2;
      // The schema for a table column.
      message Column {
        // Required for each Column that you specify. The name of the column in the
        // destination table.
        string column_name = 1;
        // Required for each Column that you specify. The type of the column.
        string type_name = 2;
      }
      // Optional. The schema for the table columns.
      repeated Column columns = 3;
    }
    // Required. The TableManifest of the tables to be imported.
    repeated TableManifest tables = 1;
  
    enum ProtoDialect {
      GOOGLE_STANDARD_SQL = 0;
      POSTGRESQL = 1;
    }
    // Optional. The dialect of the receiving database. Defaults to GOOGLE_STANDARD_SQL.
    ProtoDialect dialect = 2;
  }

  Contoh berikut menunjukkan file manifes untuk mengimpor tabel bernama Albums dan Singers ke dalam database dialek GoogleSQL. Tabel Albums menggunakan skema kolom yang diambil tugas dari database, dan tabel Singers menggunakan skema yang ditentukan oleh file manifes:

  {
    "tables": [
      {
        "table_name": "Albums",
        "file_patterns": [
          "gs://bucket1/Albums_1.csv",
          "gs://bucket1/Albums_2.csv"
        ]
      },
      {
        "table_name": "Singers",
        "file_patterns": [
          "gs://bucket1/Singers*.csv"
        ],
        "columns": [
          {"column_name": "SingerId", "type_name": "INT64"},
          {"column_name": "FirstName", "type_name": "STRING"},
          {"column_name": "LastName", "type_name": "STRING"}
        ]
      }
    ]
  }

• File teks yang akan diimpor harus dalam format CSV, dengan encoding ASCII atau UTF-8. Sebaiknya jangan gunakan tanda urutan byte (BOM) dalam file berenkode UTF-8.
• Data harus cocok dengan salah satu jenis berikut:

  GoogleSQL

      BOOL
      INT64
      FLOAT64
      NUMERIC
      STRING
      DATE
      TIMESTAMP
      BYTES
      JSON

  PostgreSQL

      boolean
      bigint
      double precision
      numeric
      character varying, text
      date
      timestamp with time zone
      bytea

Catatan: Jika Anda tidak menentukan nama kolom dan jenis data tabel target dalam file manifes impor, kolom dalam file CSV harus dalam urutan yang sama dengan kolom dalam database target. Anda dapat melihat urutan kolom di tabel dengan menjalankan kueri berikut:

SELECT * FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_NAME =
      TABLE_NAME ORDER BY ORDINAL_POSITION

Peringatan: Jika database Spanner target tidak kosong, data baru dapat menimpa data yang sudah ada.

Parameter template

Parameter	Deskripsi
instanceId	ID instance database Spanner.
databaseId	ID database dari database Spanner.
importManifest	Jalur di Cloud Storage ke file manifes impor.
columnDelimiter	Pemisah kolom yang digunakan file sumber. Nilai defaultnya adalah ,.
fieldQualifier	Karakter yang harus mengapit nilai apa pun dalam file sumber yang berisi columnDelimiter. Nilai defaultnya adalah ".
trailingDelimiter	Menentukan apakah baris dalam file sumber memiliki pemisah di akhir (yaitu, jika karakter columnDelimiter muncul di akhir setiap baris, setelah nilai kolom terakhir). Nilai defaultnya adalah true.
escape	Karakter escape yang digunakan file sumber. Secara default, parameter ini tidak ditetapkan dan template tidak menggunakan karakter escape.
nullString	String yang mewakili nilai NULL. Secara default, parameter ini tidak ditetapkan dan template tidak menggunakan string null.
dateFormat	Format yang digunakan untuk mengurai kolom tanggal. Secara default, pipeline akan mencoba mengurai kolom tanggal sebagai yyyy-M-d[' 00:00:00'], misalnya, 31-01-2019 atau 1-1-2019 00:00:00. Jika format tanggal Anda berbeda, tentukan format tersebut menggunakan pola java.time.format.DateTimeFormatter.
timestampFormat	Format yang digunakan untuk mengurai kolom stempel waktu. Jika stempel waktu berupa bilangan bulat panjang, stempel waktu tersebut akan diuraikan sebagai waktu Unix epoch. Jika tidak, string tersebut akan diuraikan sebagai string menggunakan format java.time.format.DateTimeFormatter.ISO_INSTANT. Untuk kasus lainnya, tentukan string pola Anda sendiri, misalnya menggunakan MMM dd yyyy HH:mm:ss.SSSVV untuk stempel waktu dalam bentuk "Jan 21 1998 01:02:03.456+08:00".
spannerProjectId	(Opsional) Project ID Google Cloud dari database Spanner. Jika tidak disetel, project Google Cloud default akan digunakan.
spannerPriority	(Opsional) Prioritas permintaan untuk panggilan Spanner. Nilai yang mungkin adalah HIGH, MEDIUM, LOW. Nilai defaultnya adalah MEDIUM.
handleNewLine	(Opsional) Jika true, data input dapat berisi karakter baris baru. Jika tidak, karakter baris baru akan menyebabkan error. Nilai default-nya adalah false. Mengaktifkan penanganan baris baru dapat mengurangi performa.
invalidOutputPath	(Opsional) Jalur Cloud Storage untuk menulis baris yang tidak dapat diimpor.

Jika Anda perlu menggunakan format tanggal atau stempel waktu yang disesuaikan, pastikan format tersebut adalah pola java.time.format.DateTimeFormatter yang valid. Tabel berikut menunjukkan contoh tambahan dari format yang disesuaikan untuk kolom tanggal dan stempel waktu:

Jenis	Nilai input	Format	Keterangan
DATE	2011-3-31		Secara default, template dapat mengurai format ini. Anda tidak perlu menentukan parameter dateFormat.
DATE	31-3-2011 00:00:00		Secara default, template dapat mengurai format ini. Anda tidak perlu menentukan format. Jika mau, Anda dapat menggunakan yyyy-M-d' 00:00:00'.
DATE	01 Apr, 18	dd MMM, yy
DATE	Rabu, 3 April 2019 M	EEEE, LLLL d, tttt G
TIMESTAMP	02-01-2019T11:22:33Z 2019-01-02T11:22:33.123Z 2019-01-02T11:22:33.12356789Z		Format default ISO_INSTANT dapat mengurai jenis stempel waktu ini. Anda tidak perlu memberikan parameter timestampFormat.
TIMESTAMP	1568402363		Secara default, template dapat mengurai jenis stempel waktu ini dan memperlakukannya sebagai waktu epoch Unix.
TIMESTAMP	Sel, 3 Jun 2008 11.05.30 GMT	EEE, d MMM yyyy HH:mm:ss VV
TIMESTAMP	31/12/2018 110530.123PST	tttt/BB/dd HHmmss.SSSz
TIMESTAMP	2019-01-02T11:22:33Z atau 2019-01-02T11:22:33.123Z	yyyy-MM-dd'T'HH:mm:ss[.SSS]VV	Jika kolom input adalah campuran dari 2019-01-02T11:22:33Z dan 2019-01-02T11:22:33.123Z, format default dapat mengurai jenis stempel waktu ini. Anda tidak perlu memberikan parameter format sendiri. Anda dapat menggunakan yyyy-MM-dd'T'HH:mm:ss[.SSS]VV untuk menangani kedua kasus tersebut. Anda tidak dapat menggunakan yyyy-MM-dd'T'HH:mm:ss[.SSS]'Z', karena postfix 'Z' harus diuraikan sebagai ID zona waktu, bukan literal karakter. Secara internal, kolom stempel waktu dikonversi menjadi java.time.Instant. Oleh karena itu, waktu harus ditentukan dalam UTC atau memiliki informasi zona waktu yang terkait dengannya. Tanggal dan waktu lokal, seperti 02-01-2019 11:22:33, tidak dapat diuraikan sebagai java.time.Instant yang valid.

Menjalankan template

Konsol

1. Buka halaman Create job from template Dataflow.
Buka Buat tugas dari template
2. Di kolom Job name, masukkan nama pekerjaan yang unik.
3. Opsional: Untuk Endpoint regional, pilih nilai dari menu drop-down. Region default-nya adalah us-central1.

   Untuk daftar region tempat Anda dapat menjalankan tugas Dataflow, lihat Lokasi Dataflow.

4. Dari menu drop-down Dataflow template, pilih the Text Files on Cloud Storage to Cloud Spanner template.
5. Di kolom parameter yang disediakan, masukkan parameter value Anda.
6. Klik Run job.

gcloud

Catatan: Untuk menggunakan Google Cloud CLI guna menjalankan template classic, Anda harus memiliki Google Cloud CLI versi 138.0.0 atau yang lebih baru.

Di shell atau terminal Anda, jalankan template:

gcloud dataflow jobs run JOB_NAME \
    --gcs-location gs://dataflow-templates-REGION_NAME/VERSION/GCS_Text_to_Cloud_Spanner \
    --region REGION_NAME \
    --parameters \
instanceId=INSTANCE_ID,\
databaseId=DATABASE_ID,\
importManifest=GCS_PATH_TO_IMPORT_MANIFEST

Ganti kode berikut:

• JOB_NAME: nama pekerjaan unik pilihan Anda
• VERSION: versi template yang ingin Anda gunakan

  Anda dapat menggunakan nilai berikut:

  • latest untuk menggunakan versi terbaru template, yang tersedia di folder induk tidak bertanggal di bucket— gs://dataflow-templates-REGION_NAME/latest/
  • nama versi, seperti 2023-09-12-00_RC00, untuk menggunakan versi template tertentu, yang dapat ditemukan bertingkat di folder induk bertanggal masing-masing dalam bucket— gs://dataflow-templates-REGION_NAME/
  Perhatian: Versi terbaru template mungkin diperbarui dengan perubahan yang dapat menyebabkan gangguan. Lingkungan produksi Anda harus menggunakan template yang disimpan di folder induk bertanggal terbaru agar perubahan yang dapat menyebabkan gangguan ini tidak memengaruhi alur kerja produksi Anda.
• REGION_NAME: region tempat Anda ingin men-deploy tugas Dataflow, misalnya us-central1
• INSTANCE_ID: ID instance Spanner Anda
• DATABASE_ID: ID database Spanner Anda
• GCS_PATH_TO_IMPORT_MANIFEST: jalur Cloud Storage ke file manifes impor Anda

API

Untuk menjalankan template menggunakan REST API, kirim permintaan HTTP POST. Untuk informasi selengkapnya tentang API dan cakupan otorisasinya, lihat projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/templates:launch?gcsPath=gs://dataflow-templates-LOCATION/VERSION/GCS_Text_to_Cloud_Spanner
{
   "jobName": "JOB_NAME",
   "parameters": {
       "instanceId": "INSTANCE_ID",
       "databaseId": "DATABASE_ID",
       "importManifest": "GCS_PATH_TO_IMPORT_MANIFEST"
   },
   "environment": {
       "machineType": "n1-standard-2"
   }
}

Ganti kode berikut:

• PROJECT_ID: ID project Google Cloud tempat Anda ingin menjalankan tugas Dataflow
• JOB_NAME: nama pekerjaan unik pilihan Anda
• VERSION: versi template yang ingin Anda gunakan

  Anda dapat menggunakan nilai berikut:

  • latest untuk menggunakan versi terbaru template, yang tersedia di folder induk tidak bertanggal di bucket— gs://dataflow-templates-REGION_NAME/latest/
  • nama versi, seperti 2023-09-12-00_RC00, untuk menggunakan versi template tertentu, yang dapat ditemukan bertingkat di folder induk bertanggal masing-masing dalam bucket— gs://dataflow-templates-REGION_NAME/
  Perhatian: Versi terbaru template mungkin diperbarui dengan perubahan yang dapat menyebabkan gangguan. Lingkungan produksi Anda harus menggunakan template yang disimpan di folder induk bertanggal terbaru agar perubahan yang dapat menyebabkan gangguan ini tidak memengaruhi alur kerja produksi Anda.
• LOCATION: region tempat Anda ingin men-deploy tugas Dataflow, misalnya us-central1
• INSTANCE_ID: ID instance Spanner Anda
• DATABASE_ID: ID database Spanner Anda
• GCS_PATH_TO_IMPORT_MANIFEST: jalur Cloud Storage ke file manifes impor Anda

Kode sumber template

Java

Kode sumber template ini ada di repositori GoogleCloudPlatform/DataflowTemplates di GitHub.

Langkah selanjutnya

• Pelajari Template Dataflow.
• Lihat daftar template yang disediakan Google.