תבנית Pub/Sub ל-Elasticsearch

תבנית Pub/Sub ל-Elasticsearch היא צינור עיבוד נתונים של סטרימינג שקורא הודעות ממינוי Pub/Sub, מפעיל פונקציה בהגדרת המשתמש (UDF) וכותב אותן ל-Elasticsearch כמסמכים. תבנית Dataflow משתמשת בתכונת data streams של Elasticsearch כדי לאחסן נתוני סדרות זמנים בכמה אינדקסים, ובו בזמן מספקת לכם משאב יחיד עם שם לבקשות. מקורות נתונים מתאימים ליומנים, למדדים, לעקבות ולנתונים אחרים שנוצרים באופן רציף ומאוחסנים ב-Pub/Sub.

התבנית יוצרת מקור נתונים בשם logs-gcp.DATASET-NAMESPACE, כאשר:

  • ‫DATASET הוא הערך של פרמטר התבנית dataset, או pubsub אם לא צוין.
  • ‫NAMESPACE הוא הערך של פרמטר התבנית namespace, או default אם לא צוין.

הדרישות לגבי צינורות עיבוד נתונים

  • מינוי Pub/Sub של המקור חייב להתקיים, וההודעות צריכות להיות מקודדות בפורמט JSON תקין.
  • מארח Elasticsearch שאפשר להגיע אליו באופן ציבורי במופע של Google Cloud Platform או ב-Elastic Cloud עם Elasticsearch בגרסה 7.0 ומעלה. פרטים נוספים מופיעים במאמר שילוב של Google Cloud עם Elastic.
  • נושא Pub/Sub לפלט של שגיאות.

פרמטרים של תבניות

פרמטרים נדרשים

  • ‫inputSubscription: מינוי ל-Pub/Sub לצריכת הקלט. לדוגמה, projects/<PROJECT_ID>/subscriptions/<SUBSCRIPTION_NAME>.
  • ‫errorOutputTopic: נושא הפלט ב-Pub/Sub לפרסום רשומות שנכשלו, בפורמט projects/<PROJECT_ID>/topics/<TOPIC_NAME>.
  • ‫connectionUrl: כתובת ה-URL של Elasticsearch בפורמט https://hostname:[port]. אם משתמשים ב-Elastic Cloud, צריך לציין את CloudID. לדוגמה, https://elasticsearch-host:9200.
  • ‫apiKey: מפתח ה-API בקידוד Base64 שמשמש לאימות.

פרמטרים אופציונליים

  • מערך נתונים: סוג היומנים שנשלחים באמצעות Pub/Sub, שעבורם יש לנו לוח בקרה מוכן לשימוש. הערכים המוכרים של סוגי היומנים הם audit,‏ vpcflow ו-firewall. ברירת המחדל: pubsub.
  • מרחב שמות: קיבוץ שרירותי, כמו סביבה (פיתוח, ייצור או QA), צוות או יחידה עסקית אסטרטגית. ברירת המחדל: default.
  • ‫elasticsearchTemplateVersion: מזהה גרסת התבנית של Dataflow, בדרך כלל מוגדר על ידי Google Cloud. ברירת המחדל היא: 1.0.0.
  • ‫javascriptTextTransformGcsPath: ה-URI של Cloud Storage של קובץ ה-‎ .js שמגדיר את הפונקציה בהגדרת המשתמש (UDF) ב-JavaScript שבה רוצים להשתמש. לדוגמה, gs://my-bucket/my-udfs/my_file.js.
  • ‫javascriptTextTransformFunctionName: השם של פונקציית JavaScript בהגדרת המשתמש (UDF) שבה רוצים להשתמש. לדוגמה, אם קוד הפונקציה ב-JavaScript הוא myTransform(inJson) { /*...do stuff...*/ }, אז שם הפונקציה הוא myTransform. דוגמאות לפונקציות מוגדרות על ידי המשתמש (UDF) ב-JavaScript זמינות במאמר UDF Examples (https://github.com/GoogleCloudPlatform/DataflowTemplates#udf-examples).
  • ‫javascriptTextTransformReloadIntervalMinutes: מציין את התדירות שבה יש לטעון מחדש את הפונקציה המוגדרת על ידי המשתמש, בדקות. אם הערך גדול מ-0, מערכת Dataflow בודקת מעת לעת את קובץ ה-UDF ב-Cloud Storage, ומטעינה מחדש את ה-UDF אם הקובץ משתנה. הפרמטר הזה מאפשר לכם לעדכן את ה-UDF בזמן שהצינור פועל, בלי שתצטרכו להפעיל מחדש את העבודה. אם הערך הוא 0, טעינה מחדש של UDF מושבתת. ערך ברירת המחדל הוא 0.
  • ‫elasticsearchUsername: שם המשתמש ב-Elasticsearch לאימות. אם מציינים את המאפיין apiKey, המערכת מתעלמת מהערך שלו.
  • ‫elasticsearchPassword: סיסמת Elasticsearch לאימות. אם מציינים את המאפיין apiKey, המערכת מתעלמת מהערך שלו.
  • ‫batchSize: גודל האצווה במספר המסמכים. ברירת המחדל היא 1000.
  • ‫batchSizeBytes: גודל הקבוצה במספר בייטים. ברירת המחדל היא 5242880 (5MB).
  • ‫maxRetryAttempts: המספר המקסימלי של ניסיונות חוזרים. הערך חייב להיות גדול מאפס. ברירת המחדל היא no retries.
  • ‫maxRetryDuration: משך הניסיון החוזר המקסימלי באלפיות השנייה. הערך חייב להיות גדול מאפס. ברירת המחדל היא no retries.
  • ‫propertyAsIndex: המאפיין במסמך שמבוצע בו אינדוקס, שהערך שלו מציין מטא-נתונים של _index שייכללו במסמך בבקשות בכמות גדולה. מקבל עדיפות על פני UDF של _index. ברירת המחדל היא none.
  • ‫javaScriptIndexFnGcsPath: הנתיב ב-Cloud Storage למקור של פונקציית JavaScript UDF שמציינת מטא-נתונים של _index שייכללו במסמך בבקשות בכמות גדולה. ברירת המחדל היא none.
  • ‫javaScriptIndexFnName: השם של פונקציית ה-JavaScript של ה-UDF שמציינת מטא-נתונים של _index שיש לכלול במסמך בבקשות בכמות גדולה. ברירת המחדל היא none.
  • ‫propertyAsId: מאפיין במסמך שמבצעים עליו אינדוקס, שהערך שלו מציין _id מטא-נתונים שייכללו עם המסמך בבקשות בכמות גדולה. מקבל עדיפות על פני UDF של _id. ברירת המחדל היא none.
  • ‫javaScriptIdFnGcsPath: הנתיב ב-Cloud Storage למקור של פונקציית ה-UDF ב-JavaScript, שמציין מטא-נתונים של _id שייכללו במסמך בבקשות בכמות גדולה. ברירת המחדל היא none.
  • ‫javaScriptIdFnName: השם של פונקציית ה-UDF ב-JavaScript שמציינת את המטא-נתונים של _id שייכללו במסמך בבקשות בכמות גדולה. ברירת המחדל היא none.
  • ‫javaScriptTypeFnGcsPath: הנתיב ב-Cloud Storage למקור של פונקציית JavaScript UDF שמציינת מטא-נתונים מסוג _type שיש לכלול במסמכים בבקשות בכמות גדולה. ברירת המחדל היא none.
  • ‫javaScriptTypeFnName: השם של פונקציית ה-JavaScript של ה-UDF שמציינת את המטא-נתונים של _type שיש לכלול במסמך בבקשות בכמות גדולה. ברירת המחדל היא none.
  • ‫javaScriptIsDeleteFnGcsPath: הנתיב ב-Cloud Storage למקור של פונקציית ה-UDF ב-JavaScript, שקובעת אם למחוק את המסמך במקום להוסיף או לעדכן אותו. הפונקציה מחזירה מחרוזת עם הערך true או false. ברירת המחדל היא none.
  • ‫javaScriptIsDeleteFnName: השם של פונקציית ה-JavaScript של ה-UDF שקובעת אם למחוק את המסמך במקום להוסיף או לעדכן אותו. הפונקציה מחזירה מחרוזת עם הערך true או false. ברירת המחדל היא none.
  • ‫usePartialUpdate: האם להשתמש בעדכונים חלקיים (עדכון במקום יצירה או הוספה לאינדקס, שמאפשרים מסמכים חלקיים) בבקשות Elasticsearch. ברירת המחדל היא false.
  • ‫bulkInsertMethod: האם להשתמש ב-INDEX (index, allows upserts) או ב-CREATE (create, errors on duplicate _id) עם בקשות בכמות גדולה של Elasticsearch. ברירת המחדל היא CREATE.
  • ‫trustSelfSignedCerts: האם לתת אמון באישור בחתימה עצמית או לא. יכול להיות שמופע Elasticsearch שהותקן כולל אישור בחתימה עצמית. כדי לעקוף את האימות של אישור ה-SSL, צריך להגדיר את האפשרות הזו כ-True. (ברירת המחדל: false).
  • ‫disableCertificateValidation: אם הערך הוא true, המערכת נותנת אמון באישור ה-SSL בחתימה עצמית. יכול להיות שלמופע Elasticsearch יש אישור בחתימה עצמית. כדי לעקוף את האימות של האישור, מגדירים את הפרמטר הזה לערך true. ברירת המחדל היא false.
  • ‫apiKeyKMSEncryptionKey: מפתח Cloud KMS לפענוח מפתח ה-API. חובה לכלול את הפרמטר הזה אם הערך של apiKeySource הוא KMS. אם הפרמטר הזה מסופק, צריך להעביר מחרוזת apiKey מוצפנת. הצפנת פרמטרים באמצעות נקודת הקצה להצפנה ב-KMS API. למפתח, משתמשים בפורמט projects/<PROJECT_ID>/locations/<KEY_REGION>/keyRings/<KEY_RING>/cryptoKeys/<KMS_KEY_NAME>. למידע נוסף: https://cloud.google.com/kms/docs/reference/rest/v1/projects.locations.keyRings.cryptoKeys/encrypt לדוגמה, projects/your-project-id/locations/global/keyRings/your-keyring/cryptoKeys/your-key-name.
  • ‫apiKeySecretId: המזהה הסודי ב-Secret Manager של מפתח ה-API. אם הערך של apiKeySource הוא SECRET_MANAGER, צריך לספק את הפרמטר הזה. משתמשים בפורמט projects/<PROJECT_ID>/secrets/<SECRET_ID>/versions/<SECRET_VERSION>. For example, projects/your-project-id/secrets/your-secret/versions/your-secret-version`.
  • ‫apiKeySource: המקור של מפתח ה-API. הערכים המותרים הם PLAINTEXT, ‏ KMS או SECRET_MANAGER. חובה להשתמש בפרמטר הזה כשמשתמשים ב-Secret Manager או ב-KMS. אם הערך של apiKeySource הוא KMS, צריך לספק את apiKeyKMSEncryptionKey ואת מפתח ה-API המוצפן. אם הערך של apiKeySource הוא SECRET_MANAGER, צריך לספק את הערך של apiKeySecretId. אם הערך של apiKeySource הוא PLAINTEXT, צריך לספק את הערך של apiKey. ברירת המחדל היא: PLAINTEXT.
  • ‫socketTimeout: אם ההגדרה הזו מוגדרת, היא מחליפה את ברירת המחדל של הזמן הקצוב לתפוגה של הניסיון החוזר ואת ברירת המחדל של הזמן הקצוב לתפוגה של שקע (30,000 אלפיות שנייה) ב-Elastic RestClient.

פונקציות בהגדרת המשתמש

התבנית הזו תומכת בפונקציות בהגדרת המשתמש (UDF) בכמה נקודות בצינור, כפי שמתואר בהמשך. למידע נוסף, ראו יצירת פונקציות מוגדרות על ידי המשתמש לתבניות Dataflow.

פונקציית שינוי טקסט

הופך את ההודעה ב-Pub/Sub למסמך Elasticsearch.

פרמטרים של תבניות:

  • ‫javascriptTextTransformGcsPath: ה-URI של קובץ ה-JavaScript ב-Cloud Storage.
  • ‫javascriptTextTransformFunctionName: השם של פונקציית JavaScript.

מפרט הפונקציה:

  • קלט: שדה הנתונים של הודעת Pub/Sub, שעבר סריאליזציה כמחרוזת JSON.
  • פלט: מסמך JSON שהומר למחרוזת להוספה ל-Elasticsearch.

פונקציית אינדקס

מחזירה את האינדקס שאליו המסמך שייך.

פרמטרים של תבניות:

  • ‫javaScriptIndexFnGcsPath: ה-URI של Cloud Storage של קובץ ה-JavaScript.
  • ‫javaScriptIndexFnName: השם של פונקציית JavaScript.

מפרט הפונקציה:

  • קלט: מסמך Elasticsearch שעבר סריאליזציה כמחרוזת JSON.
  • ‫Output: הערך של שדה המטא-נתונים _index במסמך.

הפונקציה Document ID

מחזירה את מזהה המסמך.

פרמטרים של תבניות:

  • ‫javaScriptIdFnGcsPath: ה-URI של קובץ ה-JavaScript ב-Cloud Storage.
  • ‫javaScriptIdFnName: השם של פונקציית JavaScript.

מפרט הפונקציה:

  • קלט: מסמך Elasticsearch שעבר סריאליזציה כמחרוזת JSON.
  • ‫Output: הערך של שדה המטא-נתונים _id במסמך.

פונקציה למחיקת מסמכים

קובע אם למחוק מסמך. כדי להשתמש בפונקציה הזו, צריך להגדיר את מצב ההוספה בכמות גדולה ל-INDEX ולספק פונקציה של מזהה מסמך.

פרמטרים של תבניות:

  • ‫javaScriptIsDeleteFnGcsPath: ה-URI של קובץ ה-JavaScript ב-Cloud Storage.
  • ‫javaScriptIsDeleteFnName: השם של פונקציית JavaScript.

מפרט הפונקציה:

  • קלט: מסמך Elasticsearch שעבר סריאליזציה כמחרוזת JSON.
  • פלט: מחזירה את המחרוזת "true" כדי למחוק את המסמך, או את המחרוזת "false" כדי לעדכן או להוסיף (upsert) את המסמך.

פונקציית מיפוי סוג

מחזירה את סוג המיפוי של המסמך.

פרמטרים של תבניות:

  • ‫javaScriptTypeFnGcsPath: ה-URI של Cloud Storage של קובץ ה-JavaScript.
  • ‫javaScriptTypeFnName: השם של פונקציית JavaScript.

מפרט הפונקציה:

  • קלט: מסמך Elasticsearch שעבר סריאליזציה כמחרוזת JSON.
  • ‫Output: הערך של שדה המטא-נתונים _type במסמך.

הפעלת התבנית

המסוף

  1. עוברים לדף Dataflow Create job from template (יצירת משימה מתבנית).
    2. כניסה לדף Create job from template
  2. בשדה שם המשימה, מזינים שם ייחודי למשימה.
  3. אופציונלי: בשדה Regional endpoint (נקודת קצה אזורית), בוחרים ערך מהתפריט הנפתח. אזור ברירת המחדל הוא us-central1.

    רשימת האזורים שבהם אפשר להריץ משימת Dataflow מופיעה במאמר מיקומי Dataflow.

  4. בתפריט הנפתח Dataflow template (תבנית של העברת נתונים), בוחרים באפשרות the Pub/Sub to Elasticsearch template.
  5. בשדות הפרמטרים שמופיעים, מזינים את ערכי הפרמטרים.
  6. לוחצים על הפעלת העבודה.

gcloud

במעטפת או בטרמינל, מריצים את התבנית:

gcloud dataflow flex-template run JOB_NAME \
    --project=PROJECT_ID \
    --region=REGION_NAME \
    --template-file-gcs-location=gs://dataflow-templates-REGION_NAME/VERSION/flex/PubSub_to_Elasticsearch_Flex \
    --parameters \
inputSubscription=SUBSCRIPTION_NAME,\
connectionUrl=CONNECTION_URL,\
dataset=DATASET,\
namespace=NAMESPACE,\
apiKey=APIKEY,\
errorOutputTopic=ERROR_OUTPUT_TOPIC

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט שבו רוצים להריץ את משימת Dataflow Google Cloud
  • ‫JOB_NAME: שם ייחודי של המשימה לפי בחירתכם
  • ‫REGION_NAME: האזור שבו רוצים לפרוס את עבודת Dataflow, לדוגמה: us-central1
  • ‫VERSION: הגרסה של התבנית שבה רוצים להשתמש

    אפשר להשתמש בערכים הבאים:

    • ‫latest כדי להשתמש בגרסה העדכנית של התבנית, שזמינה בתיקיית ההורה ללא תאריך בדלי – gs://dataflow-templates-REGION_NAME/latest/
    • שם הגרסה, כמו 2023-09-12-00_RC00, כדי להשתמש בגרסה ספציפית של התבנית, שאפשר למצוא אותה בתיקיית האב המתאימה עם התאריך בדלי – gs://dataflow-templates-REGION_NAME/
  • ‫ERROR_OUTPUT_TOPIC: נושא Pub/Sub לפלט של שגיאות
  • ‫SUBSCRIPTION_NAME: השם של המינוי שלכם ל-Pub/Sub
  • ‫CONNECTION_URL: כתובת ה-URL של Elasticsearch
  • ‫DATASET: סוג היומן
  • ‫NAMESPACE: מרחב השמות של מערך הנתונים
  • ‫APIKEY: מפתח ה-API שלכם בקידוד base64 לאימות

API

כדי להריץ את התבנית באמצעות API בארכיטקטורת REST, שולחים בקשת HTTP POST. מידע נוסף על ה-API ועל היקפי ההרשאות שלו זמין במאמר projects.templates.launch.

POST https://dataflow.googleapis.com/v1b3/projects/PROJECT_ID/locations/LOCATION/flexTemplates:launch
{
   "launch_parameter": {
      "jobName": "JOB_NAME",
      "parameters": {
          "inputSubscription": "SUBSCRIPTION_NAME",
          "connectionUrl": "CONNECTION_URL",
          "dataset": "DATASET",
          "namespace": "NAMESPACE",
          "apiKey": "APIKEY",
          "errorOutputTopic": "ERROR_OUTPUT_TOPIC"
      },
      "containerSpecGcsPath": "gs://dataflow-templates-LOCATION/VERSION/flex/PubSub_to_Elasticsearch_Flex",
   }
}

מחליפים את מה שכתוב בשדות הבאים:

  • ‫PROJECT_ID: מזהה הפרויקט שבו רוצים להריץ את משימת Dataflow Google Cloud
  • ‫JOB_NAME: שם ייחודי של המשימה לפי בחירתכם
  • ‫LOCATION: האזור שבו רוצים לפרוס את עבודת Dataflow, לדוגמה: us-central1
  • ‫VERSION: הגרסה של התבנית שבה רוצים להשתמש

    אפשר להשתמש בערכים הבאים:

    • ‫latest כדי להשתמש בגרסה העדכנית של התבנית, שזמינה בתיקיית ההורה ללא תאריך בדלי – gs://dataflow-templates-REGION_NAME/latest/
    • שם הגרסה, כמו 2023-09-12-00_RC00, כדי להשתמש בגרסה ספציפית של התבנית, שאפשר למצוא אותה בתיקיית האב המתאימה עם התאריך בדלי – gs://dataflow-templates-REGION_NAME/
  • ‫ERROR_OUTPUT_TOPIC: נושא Pub/Sub לפלט של שגיאות
  • ‫SUBSCRIPTION_NAME: השם של המינוי שלכם ל-Pub/Sub
  • ‫CONNECTION_URL: כתובת ה-URL של Elasticsearch
  • ‫DATASET: סוג היומן
  • ‫NAMESPACE: מרחב השמות של מערך הנתונים
  • ‫APIKEY: מפתח ה-API שלכם בקידוד base64 לאימות

המאמרים הבאים