תבנית של Cloud Spanner ל-Cloud Storage

אפשר להשתמש בתבנית Serverless for Apache Spark Cloud Spanner to Cloud Storage כדי לחלץ נתונים ממסדי נתונים של Spanner ל-Cloud Storage.

שימוש בתבנית

מריצים את התבנית באמצעות ה-CLI של gcloud או Dataproc API.

gcloud

לפני השימוש בנתוני הפקודה הבאים, צריך להחליף את הנתונים הבאים:

‫PROJECT_ID: חובה. מזהה הפרויקט שלכם מופיע בהגדרות IAM. Google Cloud
‫REGION: חובה. אזור Compute Engine.
‫SUBNET: אופציונלי. אם לא מציינים רשת משנה, המערכת בוחרת את רשת המשנה באזור שצוין ברשת default.
דוגמה: projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME
‫TEMPLATE_VERSION: חובה. מציינים latest כדי להשתמש בגרסה העדכנית ביותר של התבנית, או את התאריך של גרסה ספציפית, לדוגמה, 2023-03-17_v0.1.0-beta (אפשר להיכנס לכתובת gs://dataproc-templates-binaries או להריץ את הפקודה gcloud storage ls gs://dataproc-templates-binaries כדי לראות רשימה של גרסאות התבניות הזמינות).
‫INSTANCE: חובה. מזהה מכונת Spanner.
‫DATABASE: חובה. מזהה מסד הנתונים של Spanner.
‫TABLE: חובה. שם טבלת הקלט ב-Spanner או שאילתת SQL בטבלת הקלט ב-Spanner.
דוגמה (שאילתת ה-SQL צריכה להיות בתוך סוגריים): (select * from TABLE)
‫SPANNER_JDBC_DIALECT: חובה. ניב של Spanner JDBC. אפשרויות: googlesql או postgresql. ברירת המחדל היא googlesql.
‫CLOUD_STORAGE_OUTPUT_PATH: חובה. נתיב ב-Cloud Storage שבו יישמר הפלט.
דוגמה: gs://example-bucket/example-folder/
‫FORMAT: חובה. פורמט נתוני הפלט. אפשרויות: avro, parquet, csv, או json. הערה: אם avro, צריך להוסיף את file:///usr/lib/spark/connector/spark-avro.jar לדגל jars של ה-CLI של gcloud או לשדה API.
דוגמה (הקידומת file:// מתייחסת לקובץ jar של Serverless for Apache Spark):
--jars=file:///usr/lib/spark/connector/spark-avro.jar, [ ... other jars]
‫MODE: חובה. מצב כתיבה לפלט של Cloud Storage. אפשרויות: append,‏ overwrite,‏ ignore או errorifexists.
‫NUM_PARTITIONS: אופציונלי. המספר המקסימלי של מחיצות שאפשר להשתמש בהן כדי להקביל קריאות וכתיבות של טבלאות.
INPUT_PARTITION_COLUMN, LOWERBOUND, UPPERBOUND: אופציונלי. אם משתמשים בפרמטר הזה, צריך לציין את כל הפרמטרים הבאים:
- ‫INPUT_PARTITION_COLUMN: שם העמודה של חלוקת טבלת הקלט ב-Spanner.
- ‫LOWERBOUND: הגבול התחתון של עמודת החלוקה למחיצות בטבלת הקלט של Spanner, שמשמש לקביעת הצעד של החלוקה למחיצות.
- ‫UPPERBOUND: הגבול העליון של עמודת החלוקה למחיצות בטבלת הקלט של Spanner, שמשמש להחלטה על גודל הצעד של החלוקה למחיצות.
‫TEMP_VIEW ו-TEMP_QUERY: אופציונליים. אתם יכולים להשתמש בשני הפרמטרים האופציונליים האלה כדי להחיל טרנספורמציה של Spark SQL בזמן טעינת הנתונים ל-Cloud Storage. הערך של TEMP_VIEW חייב להיות זהה לשם הטבלה שמשמשת בשאילתה, והערך של TEMP_QUERY הוא הצהרת השאילתה.
‫SERVICE_ACCOUNT: אופציונלי. אם לא תציינו חשבון שירות, המערכת תשתמש בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine.
‫PROPERTY ו-PROPERTY_VALUE: אופציונליים. רשימה מופרדת בפסיקים של זוגות מאפייני Spark=value.
‫LABEL ו-LABEL_VALUE: אופציונליים. רשימה מופרדת בפסיקים של זוגות label=value.
‫LOG_LEVEL: אופציונלי. רמת הרישום ביומן. יכול להיות אחד מהערכים הבאים: ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE או WARN. ברירת מחדל: INFO.
‫KMS_KEY: אופציונלי. המפתח של Cloud Key Management Service שבו יש להשתמש להצפנה. אם לא מציינים מפתח, הנתונים מוצפנים באחסון באמצעות Google-owned and Google-managed encryption key.
דוגמה: projects/PROJECT_ID/regions/REGION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME

מריצים את הפקודה הבאה:

‫Linux,‏ macOS או Cloud Shell

gcloud dataproc batches submit spark \
    --class=com.google.cloud.dataproc.templates.main.DataProcTemplate \
    --version="1.2" \
    --project="PROJECT_ID" \
    --region="REGION" \
    --jars="gs://dataproc-templates-binaries/TEMPLATE_VERSION/java/dataproc-templates.jar" \
    --subnet="SUBNET" \
    --kms-key="KMS_KEY" \
    --service-account="SERVICE_ACCOUNT" \
    --properties="PROPERTY=PROPERTY_VALUE" \
    --labels="LABEL=LABEL_VALUE" \
    -- --template=SPANNERTOGCS \
    --templateProperty log.level="LOG_LEVEL" \
    --templateProperty project.id="PROJECT_ID" \
    --templateProperty spanner.gcs.input.spanner.id="INSTANCE" \
    --templateProperty spanner.gcs.input.database.id="DATABASE" \
    --templateProperty spanner.gcs.input.table.id="TABLE" \
    --templateProperty spanner.gcs.output.gcs.path="CLOUD_STORAGE_OUTPUT_PATH" \
    --templateProperty spanner.gcs.output.gcs.saveMode="MODE" \
    --templateProperty spanner.gcs.output.gcs.format="FORMAT" \
    --templateProperty spanner.gcs.input.sql.partitionColumn="INPUT_PARTITION_COLUMN" \
    --templateProperty spanner.gcs.input.sql.lowerBound="LOWERBOUND" \
    --templateProperty spanner.gcs.input.sql.upperBound="UPPERBOUND" \
    --templateProperty spanner.spanner.gcs.input.sql.numPartitions="NUM_PARTITIONS" \
    --templateProperty spanner.gcs.temp.table="TEMP_VIEW" \
    --templateProperty spanner.gcs.temp.query="TEMP_QUERY" \
    --templateProperty spanner.jdbc.dialect="SPANNER_JDBC_DIALECT"

‏Windows (PowerShell)

gcloud dataproc batches submit spark `
    --class=com.google.cloud.dataproc.templates.main.DataProcTemplate `
    --version="1.2" `
    --project="PROJECT_ID" `
    --region="REGION" `
    --jars="gs://dataproc-templates-binaries/TEMPLATE_VERSION/java/dataproc-templates.jar" `
    --subnet="SUBNET" `
    --kms-key="KMS_KEY" `
    --service-account="SERVICE_ACCOUNT" `
    --properties="PROPERTY=PROPERTY_VALUE" `
    --labels="LABEL=LABEL_VALUE" `
    -- --template=SPANNERTOGCS `
    --templateProperty log.level="LOG_LEVEL" `
    --templateProperty project.id="PROJECT_ID" `
    --templateProperty spanner.gcs.input.spanner.id="INSTANCE" `
    --templateProperty spanner.gcs.input.database.id="DATABASE" `
    --templateProperty spanner.gcs.input.table.id="TABLE" `
    --templateProperty spanner.gcs.output.gcs.path="CLOUD_STORAGE_OUTPUT_PATH" `
    --templateProperty spanner.gcs.output.gcs.saveMode="MODE" `
    --templateProperty spanner.gcs.output.gcs.format="FORMAT" `
    --templateProperty spanner.gcs.input.sql.partitionColumn="INPUT_PARTITION_COLUMN" `
    --templateProperty spanner.gcs.input.sql.lowerBound="LOWERBOUND" `
    --templateProperty spanner.gcs.input.sql.upperBound="UPPERBOUND" `
    --templateProperty spanner.spanner.gcs.input.sql.numPartitions="NUM_PARTITIONS" `
    --templateProperty spanner.gcs.temp.table="TEMP_VIEW" `
    --templateProperty spanner.gcs.temp.query="TEMP_QUERY" `
    --templateProperty spanner.jdbc.dialect="SPANNER_JDBC_DIALECT"

Windows‏ (cmd.exe)

gcloud dataproc batches submit spark ^
    --class=com.google.cloud.dataproc.templates.main.DataProcTemplate ^
    --version="1.2" ^
    --project="PROJECT_ID" ^
    --region="REGION" ^
    --jars="gs://dataproc-templates-binaries/TEMPLATE_VERSION/java/dataproc-templates.jar" ^
    --subnet="SUBNET" ^
    --kms-key="KMS_KEY" ^
    --service-account="SERVICE_ACCOUNT" ^
    --properties="PROPERTY=PROPERTY_VALUE" ^
    --labels="LABEL=LABEL_VALUE" ^
    -- --template=SPANNERTOGCS ^
    --templateProperty log.level="LOG_LEVEL" ^
    --templateProperty project.id="PROJECT_ID" ^
    --templateProperty spanner.gcs.input.spanner.id="INSTANCE" ^
    --templateProperty spanner.gcs.input.database.id="DATABASE" ^
    --templateProperty spanner.gcs.input.table.id="TABLE" ^
    --templateProperty spanner.gcs.output.gcs.path="CLOUD_STORAGE_OUTPUT_PATH" ^
    --templateProperty spanner.gcs.output.gcs.saveMode="MODE" ^
    --templateProperty spanner.gcs.output.gcs.format="FORMAT" ^
    --templateProperty spanner.gcs.input.sql.partitionColumn="INPUT_PARTITION_COLUMN" ^
    --templateProperty spanner.gcs.input.sql.lowerBound="LOWERBOUND" ^
    --templateProperty spanner.gcs.input.sql.upperBound="UPPERBOUND" ^
    --templateProperty spanner.spanner.gcs.input.sql.numPartitions="NUM_PARTITIONS" ^
    --templateProperty spanner.gcs.temp.table="TEMP_VIEW" ^
    --templateProperty spanner.gcs.temp.query="TEMP_QUERY" ^
    --templateProperty spanner.jdbc.dialect="SPANNER_JDBC_DIALECT"

REST

לפני שמשתמשים בנתוני הבקשה, צריך להחליף את הנתונים הבאים:

‫PROJECT_ID: חובה. מזהה הפרויקט שלכם מופיע בהגדרות IAM. Google Cloud
‫REGION: חובה. אזור Compute Engine.
‫SUBNET: אופציונלי. אם לא מציינים רשת משנה, נבחרת רשת המשנה באזור שצוין ברשת default.
דוגמה: projects/PROJECT_ID/regions/REGION/subnetworks/SUBNET_NAME
‫TEMPLATE_VERSION: חובה. מציינים latest לגרסה העדכנית ביותר של התבנית, או את התאריך של גרסה ספציפית, לדוגמה, 2023-03-17_v0.1.0-beta (אפשר להיכנס לכתובת gs://dataproc-templates-binaries או להריץ את הפקודה gcloud storage ls gs://dataproc-templates-binaries כדי לראות רשימה של גרסאות התבניות הזמינות).
‫INSTANCE: חובה. מזהה מכונת Spanner.
‫DATABASE: חובה. מזהה מסד הנתונים של Spanner.
‫TABLE: חובה. שם טבלת הקלט ב-Spanner או שאילתת SQL בטבלת הקלט ב-Spanner.
דוגמה (שאילתת ה-SQL צריכה להיות בתוך סוגריים): (select * from TABLE)
‫SPANNER_JDBC_DIALECT: חובה. ניב של Spanner JDBC. אפשרויות: googlesql או postgresql. ברירת המחדל היא googlesql.
‫CLOUD_STORAGE_OUTPUT_PATH: חובה. נתיב ב-Cloud Storage שבו יישמר הפלט.
דוגמה: gs://example-bucket/example-folder/
‫FORMAT: חובה. פורמט נתוני הפלט. אפשרויות: avro, parquet, csv, או json. הערה: אם avro, צריך להוסיף את file:///usr/lib/spark/connector/spark-avro.jar לדגל jars של ה-CLI של gcloud או לשדה API.
דוגמה (הקידומת file:// מתייחסת לקובץ jar של Serverless for Apache Spark):
--jars=file:///usr/lib/spark/connector/spark-avro.jar, [ ... other jars]
‫MODE: חובה. מצב כתיבה לפלט של Cloud Storage. אפשרויות: append,‏ overwrite,‏ ignore או errorifexists.
‫NUM_PARTITIONS: אופציונלי. המספר המקסימלי של מחיצות שאפשר להשתמש בהן כדי להקביל קריאות וכתיבות של טבלאות.
INPUT_PARTITION_COLUMN, LOWERBOUND, UPPERBOUND: אופציונלי. אם משתמשים בפרמטר הזה, צריך לציין את כל הפרמטרים הבאים:
- ‫INPUT_PARTITION_COLUMN: שם העמודה של חלוקת טבלת הקלט ב-Spanner.
- ‫LOWERBOUND: הגבול התחתון של עמודת החלוקה למחיצות בטבלת הקלט של Spanner, שמשמש לקביעת הצעד של החלוקה למחיצות.
- ‫UPPERBOUND: הגבול העליון של עמודת החלוקה למחיצות בטבלת הקלט של Spanner, שמשמש להחלטה על גודל הצעד של החלוקה למחיצות.
‫TEMP_VIEW ו-TEMP_QUERY: אופציונליים. אתם יכולים להשתמש בשני הפרמטרים האופציונליים האלה כדי להחיל טרנספורמציה של Spark SQL בזמן טעינת הנתונים ל-Cloud Storage. הערך של TEMP_VIEW חייב להיות זהה לשם הטבלה שמשמשת בשאילתה, והערך של TEMP_QUERY הוא הצהרת השאילתה.
‫SERVICE_ACCOUNT: אופציונלי. אם לא תציינו חשבון שירות, המערכת תשתמש בחשבון השירות שמוגדר כברירת מחדל ב-Compute Engine.
‫PROPERTY ו-PROPERTY_VALUE: אופציונליים. רשימה מופרדת בפסיקים של זוגות מאפייני Spark=value.
‫LABEL ו-LABEL_VALUE: אופציונליים. רשימה מופרדת בפסיקים של זוגות label=value.
‫LOG_LEVEL: אופציונלי. רמת הרישום ביומן. יכול להיות אחד מהערכים הבאים: ALL, DEBUG, ERROR, FATAL, INFO, OFF, TRACE או WARN. ברירת מחדל: INFO.
‫KMS_KEY: אופציונלי. המפתח של Cloud Key Management Service שבו יש להשתמש להצפנה. אם לא מציינים מפתח, הנתונים מוצפנים באחסון באמצעות Google-owned and Google-managed encryption key.
דוגמה: projects/PROJECT_ID/regions/REGION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME

ה-method של ה-HTTP וכתובת ה-URL:

POST https://dataproc.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/batches

תוכן בקשת JSON:


{
  "environmentConfig":{
    "executionConfig":{
      "subnetworkUri":"SUBNET",
      "kmsKey": "KMS_KEY",
      "serviceAccount": "SERVICE_ACCOUNT"
    }
  },
  "labels": {
    "LABEL": "LABEL_VALUE"
  },
  "runtimeConfig": {
    "version": "1.2",
    "properties": {
      "PROPERTY": "PROPERTY_VALUE"
    }
  },
  "sparkBatch":{
    "mainClass":"com.google.cloud.dataproc.templates.main.DataProcTemplate",
    "args":[
      "--template","SPANNERTOGCS",
      "--templateProperty","log.level=LOG_LEVEL",
      "--templateProperty","project.id=PROJECT_ID",
      "--templateProperty","spanner.gcs.input.spanner.id=INSTANCE",
      "--templateProperty","spanner.gcs.input.database.id=DATABASE",
      "--templateProperty","spanner.gcs.input.table.id=TABLE",
      "--templateProperty","spanner.gcs.output.gcs.path=CLOUD_STORAGE_OUTPUT_PATH",
      "--templateProperty","spanner.gcs.output.gcs.saveMode=MODE",
      "--templateProperty","spanner.gcs.output.gcs.format=FORMAT",
      "--templateProperty","spanner.gcs.input.sql.partitionColumn=INPUT_PARTITION_COLUMN",
      "--templateProperty","spanner.gcs.input.sql.lowerBound=LOWERBOUND",
      "--templateProperty","spanner.gcs.input.sql.upperBound=UPPERBOUND",
      "--templateProperty","spanner.gcs.input.sql.numPartitions=NUM_PARTITIONS",
      "--templateProperty","spanner.gcs.temp.table=TEMP_VIEW",
      "--templateProperty","spanner.gcs.temp.query=TEMP_QUERY",
      "--templateProperty spanner.jdbc.dialect=SPANNER_JDBC_DIALECT"
    ],
    "jarFileUris":[
      "file:///usr/lib/spark/connector/spark-avro.jar", "gs://dataproc-templates-binaries/TEMPLATE_VERSION/java/dataproc-templates.jar"
    ]
  }
}

כדי לשלוח את הבקשה צריך להרחיב אחת מהאפשרויות הבאות:

‫Curl (Linux,‏ macOS או Cloud Shell)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login, או באמצעות Cloud Shell שמחבר אתכם אוטומטית ל-CLI של gcloud. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://dataproc.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/batches"

‎PowerShell (Windows)

הערה: הפקודה הבאה מבוססת על ההנחה שנכנסתם ל-CLI של gcloud באמצעות חשבון המשתמש שלכם, על ידי הרצת gcloud init או gcloud auth login. כדי לבדוק איזה חשבון פעיל, אפשר להריץ את הפקודה gcloud auth list.

שומרים את גוף הבקשה בקובץ בשם request.json ומריצים את הפקודה הבאה:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://dataproc.googleapis.com/v1/projects/PROJECT_ID/locations/REGION/batches" | Select-Object -Expand Content

אתם אמורים לקבל תגובת JSON שדומה לזו:


{
  "name": "projects/PROJECT_ID/regions/REGION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.dataproc.v1.BatchOperationMetadata",
    "batch": "projects/PROJECT_ID/locations/REGION/batches/BATCH_ID",
    "batchUuid": "de8af8d4-3599-4a7c-915c-798201ed1583",
    "createTime": "2023-02-24T03:31:03.440329Z",
    "operationType": "BATCH",
    "description": "Batch"
  }
}