Halaman ini diterjemahkan oleh Cloud Translation API.

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 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 yang sesuai 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 buffer protokol:

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 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 byte order mark (BOM) dalam file yang dienkode 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

Parameter template

Parameter yang diperlukan

instanceId: ID instance database Spanner.
databaseId: ID database database Spanner.
importManifest: Jalur di Cloud Storage yang akan digunakan saat mengimpor file manifes. Contoh, gs://your-bucket/your-folder/your-manifest.json.

Parameter opsional

spannerHost: Endpoint Cloud Spanner yang akan dipanggil dalam template. Hanya digunakan untuk pengujian. Contoh, https://batch-spanner.googleapis.com. Secara default: https://batch-spanner.googleapis.com.
columnDelimiter: Pemisah kolom yang digunakan file sumber. Nilai defaultnya adalah ,. Misalnya, ,.
fieldQualifier: Karakter yang harus mengapit nilai apa pun dalam file sumber yang berisi columnDelimiter. Nilai defaultnya adalah tanda kutip ganda.
trailingDelimiter: Menentukan apakah baris dalam file sumber memiliki pemisah akhir, yaitu apakah 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 mencoba mengurai kolom tanggal sebagai yyyy-M-d[' 00:00:00'], misalnya, sebagai 2019-01-31 atau 2019-1-1 00:00:00. Jika format tanggal Anda berbeda, tentukan format menggunakan pola java.time.format.DateTimeFormatter (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html).
timestampFormat: Format yang digunakan untuk mengurai kolom stempel waktu. Jika stempel waktu adalah bilangan bulat panjang, stempel waktu akan diuraikan sebagai waktu epoch Unix. Jika tidak, nilai akan diuraikan sebagai string menggunakan format java.time.format.DateTimeFormatter.ISO_INSTANT (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html#ISO_INSTANT). Untuk kasus lain, 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: ID project Google Cloud yang berisi database Spanner. Jika tidak ditetapkan, project ID project Google Cloud default akan digunakan.
spannerPriority: Prioritas permintaan untuk panggilan Spanner. Nilai yang mungkin adalah HIGH, MEDIUM, dan LOW. Nilai defaultnya adalah MEDIUM.
handleNewLine: Jika true, data input dapat berisi karakter baris baru. Jika tidak, karakter baris baru akan menyebabkan error. Nilai defaultnya adalah false. Mengaktifkan penanganan baris baru dapat mengurangi performa.
invalidOutputPath: Jalur Cloud Storage yang akan digunakan saat menulis baris yang tidak dapat diimpor. Contoh, gs://your-bucket/your-path. Default-nya adalah kosong.

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

Jenis	Nilai input	Format	Catatan
`DATE`	2011-3-31		Secara default, template dapat mengurai format ini. Anda tidak perlu menentukan parameter `dateFormat`.
`DATE`	31-03-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, yyyy G
`TIMESTAMP`	2019-01-02T11: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`	Tue, 3 Jun 2008 11:05:30 GMT	EEE, d MMM yyyy HH:mm:ss VV
`TIMESTAMP`	2018/12/31 110530.123PST	yyyy/MM/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 Anda 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 akhiran 'Z' harus diuraikan sebagai ID zona waktu, bukan literal karakter. Secara internal, kolom stempel waktu dikonversi menjadi `java.time.Instant`. Oleh karena itu, stempel waktu harus ditentukan dalam UTC atau memiliki informasi zona waktu yang terkait dengannya. DateTime lokal, seperti 2019-01-02 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 Nama tugas, masukkan nama tugas yang unik.
Opsional: Untuk Endpoint regional, pilih nilai dari menu drop-down. Region defaultnya adalah us-central1.
Untuk mengetahui 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 nilai parameter Anda.
Klik Run job.

gcloud

Di shell atau terminal, 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 tugas unik pilihan Anda
VERSION: versi template yang ingin Anda gunakan
Anda dapat menggunakan nilai berikut:
- latest untuk menggunakan template versi terbaru, yang tersedia di folder induk tanpa tanggal 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 dalam folder induk bertanggal masing-masing di bucket—gs://dataflow-templates-REGION_NAME/
Perhatian: Template versi terbaru mungkin diupdate dengan perubahan yang dapat menyebabkan gangguan. Lingkungan produksi Anda harus menggunakan template yang disimpan di folder induk bertanggal terbaru untuk mencegah perubahan yang menyebabkan error ini 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 POST HTTP. Untuk mengetahui 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 tugas unik pilihan Anda
VERSION: versi template yang ingin Anda gunakan
Anda dapat menggunakan nilai berikut:
- latest untuk menggunakan template versi terbaru, yang tersedia di folder induk tanpa tanggal 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 dalam folder induk bertanggal masing-masing di bucket—gs://dataflow-templates-REGION_NAME/
Perhatian: Template versi terbaru mungkin diupdate dengan perubahan yang dapat menyebabkan gangguan. Lingkungan produksi Anda harus menggunakan template yang disimpan di folder induk bertanggal terbaru untuk mencegah perubahan yang menyebabkan error ini 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.