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

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

Buka halaman Create job from template Dataflow.

Buka Buat tugas dari template

Di kolom Job name, masukkan nama pekerjaan yang unik.
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.
Dari menu drop-down Dataflow template, pilih the Text Files on Cloud Storage to Cloud Spanner template.
Di kolom parameter yang disediakan, masukkan parameter value Anda.
Klik Run job.

gcloud

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.