Cloud Storage 文字到 Spanner 範本

「Cloud Storage 文字到 Spanner」範本是一種批次管道，可從 Cloud Storage 讀取 CSV 文字檔案，並將這些 CSV 文字檔案匯入 Spanner 資料庫。

管道相關規定

• 必須具備目標 Spanner 資料庫和資料表。
• 您要有 Cloud Storage 值區的讀取權限及目標 Spanner 資料庫的寫入權限。
• 包含 CSV 檔案的輸入 Cloud Storage 路徑必須已存在。
• 您必須建立包含 CSV 檔案 JSON 說明的匯入資訊清單檔案，且必須將該資訊清單檔案儲存在 Cloud Storage 中。
• 如果目標 Spanner 資料庫已有結構定義，在資訊清單檔案中指定的任何資料欄都必須具有與目標資料庫結構定義中對應的資料欄相同的資料類型。

• 使用 ASCII 或 UTF-8 編碼的資訊清單檔案必須符合下列格式：

  資訊清單格式和範例

  資訊清單檔案的格式會對應到下列訊息類型，如通訊協定緩衝區格式中所示：

  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;
  }

  以下範例顯示匯入資料表 Albums 和 Singers 的資訊清單檔案，這些資料表會匯入 GoogleSQL 方言資料庫。Albums 資料表使用工作擷取自資料庫的資料欄結構定義，而 Singers 資料表使用資訊清單檔案所指定的結構定義：

  {
    "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"}
        ]
      }
    ]
  }

• 要匯入的文字檔案必須採用 ASCII 或 UTF-8 編碼的 CSV 格式。我們建議不要在 UTF-8 編碼的檔案中使用位元組順序標記 (BOM)。
• 資料必須符合下列其中一種類型：

  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

範本參數

必要參數

• instanceId：Spanner 資料庫的執行個體 ID。
• databaseId：Spanner 資料庫的資料庫 ID。
• importManifest：匯入資訊清單檔案時要使用的 Cloud Storage 路徑。例如：gs://your-bucket/your-folder/your-manifest.json。

選用參數

• spannerHost：要在範本中呼叫的 Cloud Spanner 端點。僅供測試。例如，https://batch-spanner.googleapis.com。預設值為：https://batch-spanner.googleapis.com。
• columnDelimiter：來源檔案使用的資料欄分隔符號。預設值為 ,。例如：,。
• fieldQualifier：在包含 columnDelimiter 的來源檔案中，任何值前後應加上的字元。預設值為雙引號。
• trailingDelimiter：指出來源檔案中的行是否具有結尾的分隔符號，也就是說，在最後一個資料欄值之後，columnDelimiter 字元是否出現在每行的結尾。預設值為 true。
• escape：來源檔案使用的逸出字元。根據預設，此參數並未設定，且範本也不會使用逸出字元。
• nullString：代表 NULL 值的字串。根據預設，此參數並未設定，且範本也不會使用 NULL 字串。
• dateFormat：用來剖析日期資料欄的格式。根據預設，管道會嘗試將日期資料欄剖析為 yyyy-M-d[' 00:00:00']，例如 2019-01-31 或 2019-1-1 00:00:00。如果日期格式不同，請使用 java.time.format.DateTimeFormatter (https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/format/DateTimeFormatter.html) 模式指定格式。
• timestampFormat：用來剖析時間戳記資料欄的格式。如果時間戳記是長整數，則會解析為 Unix 紀元時間。否則，系統會使用 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) 格式將其剖析為字串。如為其他情況，請指定您自己的模式字串，例如使用 MMM dd yyyy HH:mm:ss.SSSVV 以 Jan 21 1998 01:02:03.456+08:00 的形式呈現時間戳記。
• spannerProjectId：包含 Spanner 資料庫的 Google Cloud 專案 ID。如未設定，系統會使用預設 Google Cloud 專案的專案 ID。
• spannerPriority：Spanner 呼叫的請求優先順序。可能的值為 HIGH、MEDIUM 和 LOW。預設值為 MEDIUM。
• handleNewLine：如果為 true，輸入資料可包含換行符號字元。否則，換行字元會導致錯誤。預設值為 false。啟用換行符處理功能可能會降低效能。
• invalidOutputPath：寫入無法匯入的資料列時要使用的 Cloud Storage 路徑。例如，gs://your-bucket/your-path。預設為空白。

如果您需要使用自訂的日期或時間戳記格式，請確保其為有效的 java.time.format.DateTimeFormatter 模式。下表顯示日期和時間戳記資料欄的其他自訂格式範例：

執行範本

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

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