פתרון בעיות ב-Dataform

במאמר הזה מוסבר איך לפתור בעיות ב-Dataform.

הגישה ל-BigQuery נדחתה

השגיאה הבאה מתרחשת כשמפעילים קריאה לצינור לפני שמעניקים ל-Dataform גישה ל-BigQuery:

Access Denied: Project PROJECT_ID: User does not have bigquery.jobs.create permission in project PROJECT_ID.

כדי לפתור את השגיאה, צריך לתת ל-Dataform גישה ל-BigQuery.

אסימון הגישה למאגר מרוחק נדחה

השגיאה הבאה מתרחשת כשאין לטוקן האימות שלכם למאגר צד שלישי מקושר גישה למאגר הזה:

The access token for remote repository REPOSITORY_NAME was rejected

כדי לפתור את השגיאה, צריך לבדוק את ההרשאות הנדרשות בספק Git ולעדכן את אסימון האימות של Secret Manager בהתאם. איך מאמתים מאגרי Git של צד שלישי ב-Dataform

בחיבור של Secure Source Manager חסר שרת proxy של Developer Connect

השגיאה הבאה מתרחשת כשמקשרים מאגר של Dataform למאגר של Secure Source Manager (תצוגה מקדימה) באמצעות חיבור Developer Connect שהשרת proxy לא מופעל בו:

This repository uses a Secure Source Manager connection that does not have the Developer Connect proxy enabled. Dataform cannot access it. Select a different repository, or link a new repository using a connection with the proxy enabled.

כדי לפתור את השגיאה, בוחרים מאגר אחר, מקשרים מאגר חדש באמצעות חיבור עם שרת proxy מופעל, או מעדכנים את החיבור הקיים של Developer Connect כדי להפעיל את שרת ה-proxy. למידע נוסף, אפשר לקרוא את המאמר בנושא חיבור מאגר מרוחק באמצעות Developer Connect.

יש חריגה ממגבלת הבו-זמניות (concurrency) של שאילתות ב-BigQuery

השגיאה הבאה מתרחשת כשמספר השאילתות המקבילות שמופעלות ב-BigQuery חורג ממגבלת המקבילות של שאילתות ב-BigQuery:

Exceeded rate limits: too many concurrent queries for this project_and_region

כדי לפתור את השגיאה הזו, צריך לצמצם את מספר השאילתות המקבילות לפחות מ-250 באחת מהדרכים הבאות:

הוראות לפתרון השגיאה הזו ב-BigQuery זמינות במאמר פתרון בעיות שקשורות למכסות ולמגבלות.

חרגתם מהמכסה ב-BigQuery

השגיאה הבאה מתרחשת כשמספר בקשות ה-API ש-Dataform שולח ל-BigQuery חורג מהמכסה של BigQuery:

Quota exceeded: Your user_method exceeded quota for concurrent api requests
per user per method.

כדי לפתור את השגיאה הזו, צריך לצמצם את מספר השאילתות המקבילות לפחות מ-250 באחת מהדרכים הבאות:

הוראות לפתרון השגיאה הזו ב-BigQuery זמינות במאמר פתרון בעיות שקשורות למכסות ולמגבלות.

שגיאות בהפעלת צינור עיבוד נתונים ב-BigQuery

השגיאות הבאות מתרחשות במהלך הביצוע של תהליך עבודה ב-BigQuery:

כדי לפתור את השגיאות האלה, אפשר לעיין במאמר הודעות שגיאה ב-BigQuery.

הקומפילציה נכשלת

השגיאות הבאות מתרחשות במהלך ההידור בגלל הגודל או המספר של השאילתות שעברו הידור:

  • Compilation timed out. Reduce the complexity of your project to ensure it can compile within limits.
  • Compilation exceeded its allowed heap memory limits. Reduce the complexity of your project to ensure it can compile within limits.
  • Compilation exceeded its allowed ArrayBuffer or string memory limits. Reduce the complexity of your project to ensure it can compile within limits.

כדי לפתור את השגיאות האלה, צריך לבצע את השלבים הבאים:

  1. מעדכנים את Dataform core לגרסה האחרונה.
  2. בודקים את תהליך העבודה כדי לזהות ולצמצם חוסר יעילות.
  3. להקטין את הגודל של שאילתות SQL.

  4. כדאי לצמצם את מספר הפעולות של JavaScript בזיכרון, למשל:

    config { config {type: "table" }}
js {
    const tooBig = new Uint8Array(110_000_000);
}
SELECT ...

  5. פיצול המאגר.

מידע נוסף על מגבלות המשאבים של הידור ב-Dataform זמין במאמר מכסות ומגבלות.

מאפייני includeDependentAssertions שמתנגשים

השגיאה הבאה מתרחשת במהלך הידור כשמגדירים את הפרמטר includeDependentAssertions לאותה פעולה עם ערכים שונים בקובץ אחד:

Conflicting "includeDependentAssertions" properties are not allowed. Dependency
dependencyName has different values set for this property.

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

מידע נוסף על השימוש בפרמטר includeDependentAssertions להגדרת הצהרות כתלויות זמין במאמר הגדרת ההצהרות של פעולה נבחרת כתלויות.

צירוף חשבונות שירות בין פרויקטים חסום

השגיאה הבאה מתרחשת כשמנסים להשתמש בחשבון שירות בהתאמה אישית מפרויקט אחר, ולא מהמאגר של Dataform, והפעולה נחסמת על ידי אילוץ של מדיניות הארגון:

The caller does not have permission to act as service account: SERVICE_ACCOUNT_EMAIL

כדי לפתור את השגיאה:

  1. מזהים את הפרויקט ב- Google Cloud שבו נמצא חשבון השירות בהתאמה אישית.
  2. בפרויקט הזה, משביתים את האילוץ iam.disableCrossProjectServiceAccountUsage במדיניות הארגון. מידע נוסף זמין במאמר הפעלה של צירוף חשבונות שירות בין פרויקטים.
  3. מוודאים שלחשבון המשתמש של המתקשר יש את התפקיד 'משתמש בחשבון שירות' (roles/iam.serviceAccountUser) בחשבון השירות המותאם אישית.

למידע נוסף, קראו את המאמר טיפול בצירוף של חשבון שירות בפרויקטים שונים.

‫@dataform/core שגיאות תלות

השגיאות הבאות מתרחשות במהלך ההידור אם התלות dataform-core ב-package.json לא עדכנית:

Failed to resolve @dataform/core

@dataform/core version should be X.X.X or newer

התלות @dataform/core נדרשת ב-package.json. כשמאתחלים את סביבת העבודה הראשונה במאגר, Dataform מאכלס באופן אוטומטי את package.json בגרסה הנוכחית של @dataform/core. צריך לעדכן את @dataform/core לגרסה העדכנית ביותר כשהיא יוצאת.

כדי לפתור את השגיאות האלה, צריך לעדכן את @dataform/core לגרסה העדכנית.

ההרשאה לפרטי הכניסה של משתמש הקצה נדחתה

השגיאה הבאה מתרחשת כשמריצים את עומס העבודה באמצעות פרטי כניסה של משתמש לחשבון Google, אבל ל-Dataform אין את ההרשאות הנדרשות:

Dataform does not have the necessary permissions to run your workload using end user credentials. Error details: Account restricted: https://accounts.google.com/info/servicerestricted?...

השגיאה הזו יכולה להופיע אם בארגון שלכם מוגדרים כללים של בקרת גישה מבוססת-הקשר שמגבילים את הגישה לשירותים Google Cloud על סמך זהות המשתמש וההקשר.

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

כדי לקבל את מזהה לקוח OAuth עבור Dataform, צריך לפנות אל Cloud Customer Care.

לא ניתן לפתור את הבעיה dataform.json

השגיאה הבאה מתקבלת כשמפעילים סביבת עבודה ב-Dataform, אבל תהליך ההפעלה לא מצליח להתקין את כל החבילות:

Uncaught Error: Failed to resolve dataform.json

כדי לפתור את השגיאה, פותחים את package.json בסביבת העבודה ולוחצים על Install packages (התקנת חבילות).

הפעולה נכשלה: workflow_settings.yaml

השגיאה הבאה מתרחשת כשמפעילים סביבת עבודה של Dataform, אבל תהליך ההפעלה נכשל בהתקנת כל החבילות:

Uncaught Error: Failed to resolve workflow_settings.yaml

כדי לפתור את השגיאה, פותחים את workflow_settings.yaml בסביבת העבודה ולוחצים על Install packages.

אין תמיכה ביעדי חבילות git+

השגיאה הבאה מתקבלת כשמגדירים חבילות ב-package.json עם יעדים שמתחילים ב-git+:

'git+' prefixed package targets are not currently supported. However,
in most cases they can be used via a '.tar.gz' suffixed target instead.

ב-Dataform אין תמיכה ביעדי חבילות שמופיע לפניהם הקידומת git+.

כדי לפתור את השגיאה הזו, צריך ליצור כתובת URL של החבילה tar.gz ולעדכן את יעד החבילה ב-package.json. מידע נוסף על התקנת חבילות ב-Dataform זמין במאמר התקנת חבילה.

הזמן הקצוב להתקנת החבילה פג

השגיאה הבאה מתרחשת כשגודל החבילות שמוגדרות ב-package.json חורג מהגודל המקסימלי של יחסי התלות של NPM:

API request error: Package installation timed out

כדי לפתור את השגיאה, צריך להסיר חבילות מיותרות מ-package.json. חשוב לוודא שקובץ package.json לא מכיל @dataform/cli, ושהגודל הכולל של יחסי התלות המוגדרים ב-NPM לא חורג מ-200MB.

אם הגדרות הגרסה מפנות ל-commitish של Git, צריך לוודא שקובצי ה-package.json ביעדים שלהם תקינים.

אין הרשאה לפעול כחשבון שירות

השגיאה הבאה מתרחשת כשלחשבון הראשי שמבצע את הפעולה חסרה ההרשאה iam.serviceAccounts.actAs בחשבון השירות הרלוונטי:

Permission denied: Principal CALLER_EMAIL is missing 'iam.serviceAccounts.actAs' permission on service account SERVICE_ACCOUNT_EMAIL.

השגיאה הזו יכולה להתרחש במהלך הפעולות הבאות:

  • יצירה או עדכון של מאגר.
  • יצירה או עדכון של הגדרת תהליך עבודה.
  • יצירת הפעלה של תהליך עבודה.
  • עדכון הגדרות של גרסה.

כדי לפתור את השגיאה, צריך להעניק לחשבון המשתמש את התפקיד 'משתמש בחשבון שירות' (roles/iam.serviceAccountUser) בחשבון השירות הרלוונטי. מידע נוסף זמין במאמר הקצאת תפקידי IAM הנדרשים.

אי אפשר להגיע למאגר חבילות פרטי

השגיאה הבאה מתרחשת כשתוקף האימות של Dataform לחבילה פרטית פג:

Permission denied when fetching one or more npm packages. Please verify that
private registry authentication details are valid for each npm registry

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

אי אפשר להגיע למאגר מרוחק

אחת מהשגיאות הבאות מתרחשת כש-Dataform לא מצליח להתחבר למאגר Git המרוחק:

Remote repository 'REMOTE_REPOSITORY_URL' could not be reached.

Error during remote operation: SSH connection to remote repository 'REMOTE_REPOSITORY_URL' timed out.

Error during remote operation: `Read timed out`.

Error during remote operation: `Connection time out`.

Error during remote operation: The remote repository 'REMOTE_REPOSITORY_URL' closed connection during remote operation.

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

כשלים קבועים בחיבור

אם השגיאה מתרחשת באופן עקבי בכל ניסיון הידור או במהלך ההגדרה הראשונית של המאגר, כשל החיבור הוא קבוע. החיבור לא מוגדר בצורה נכונה או שפרטי הכניסה לא בתוקף. כדי לפתור את השגיאה, מבצעים את השלבים הבאים:

  1. מוודאים שאפשר לגשת למארח של מאגר Git מהאינטרנט הציבורי.
  2. אם מאגר Git המרוחק לא נגיש דרך האינטרנט הציבורי, אפשר להשתמש ב-Developer Connect כדי להתחבר בצורה מאובטחת מ-Dataform.
  3. מוודאים שאסימון האימות או מפתחות ה-SSH תקינים, לא פג תוקפם ויש להם גישה למאגר.
  4. פועלים לפי כל השלבים במאמר חיבור למאגר Git של צד שלישי.

כשלים זמניים או לסירוגין בחיבור

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

כדי לשפר את אמינות הייצור ולמנוע שגיאות חיבור זמניות, מומלץ לפעול לפי השיטות המומלצות הבאות:

  1. מומלץ להימנע מהידור תכוף של commitish בסביבת ייצור: קריאה ל-CreateCompilationResult ישירות ב-commitish של Git, כמו main או תג Git ספציפי, מחייבת את Dataform לבצע שיבוט Git חדש ולהתקין חבילות ברשת בכל הפעלה. הפעלה של קומפילציות תכופות של commitish בכמה צינורות עיבוד נתונים מגבירה את התלות ברשת החיצונית ואת זמן האחזור של הביצוע.
  2. שימוש בהגדרות מוצר: להפעלה בסביבת ייצור, השתמשו בהגדרות מוצר. הגדרת גרסה מקמפלת את המאגר לפי לוח זמנים מבוקר ושומרת את תוצאת הקומפילציה הבלתי ניתנת לשינוי. הפעלות של תהליכי עבודה במורד הזרם משתמשות בתוצאה הזו שנשמרה במטמון באופן מיידי, בלי לשלוח שאילתות למאגר ה-Git החיצוני.
  3. הפעלות מתוזמנות בהפרש זמן: כשמתזמנים כמה קומפילציות או טריגרים של פרסום, כדאי לתזמן אותם בהפרש זמן כדי לחלק את העומס ברשת. לדוגמה, אפשר להגדיר הפרש של 5-10 דקות בין לוחות הזמנים במקום להריץ את כל המשימות בו-זמנית.
  4. הוספת ניסיונות חוזרים בתהליכי עבודה של תזמור: כשמתזמרים הידורים של Dataform מתזמונים חיצוניים כמו Managed Service for Apache Airflow, צריך להגדיר ניסיונות חוזרים אוטומטיים עם השהיה מעריכית לפני ניסיון חוזר (exponential backoff) באופרטור כדי לטפל בצורה חלקה בחוסר אמינות זמני של הרשת. לדוגמה, ב-DAG של Airflow שמשתמש ב-DataformCreateCompilationResultOperator, מגדירים ניסיונות חוזרים באופן הבא:
from datetime import timedelta
from airflow.providers.google.cloud.operators.dataform import (
    DataformCreateCompilationResultOperator,
)

create_compilation_result = DataformCreateCompilationResultOperator(
    task_id="create_compilation_result",
    project_id="PROJECT_ID",
    region="REGION",
    repository_id="REPOSITORY_ID",
    compilation_result={
        "git_commitish": "GIT_COMMITISH",
    },
    retries=5,
    retry_delay=timedelta(minutes=2),
    retry_exponential_backoff=True,
)

מאגרים לא מוצגים ב-Dataform

יכול להיות שחלק מהמאגרים של Dataform יופיעו בחיפושים של מאגר משאבי ענן או בביקורות של הרשאות IAM, אבל הם לא יופיעו ב-Dataform במסוף Google Cloud .

במאמר זיהוי מאגרים של נכסי BigQuery מוסבר איך לזהות את המקור של המאגרים האלה באמצעות תוויות.

אין גישה לסוד של מאגר מרוחק

השגיאה הבאה מתרחשת כשסוכן השירות של Dataform לא יכול לגשת לסוד של Secret Manager עבור מאגר צד שלישי מקושר:

Dataform's service account is unable to reach the configured secret.
Make sure the secret exists and is shared with your Dataform service account:
SERVICE_ACCOUNT_ID.

כדי לפתור את השגיאה, צריך לוודא לסוכן השירות של Dataform יש גישה לסוד.

חשבון השירות לא מופיע בתפריט הנפתח

כשמגדירים מאגר או הפעלה של תהליך עבודה, יכול להיות שחשבון שירות מותאם אישית קיים לא יופיע בתפריט Service account.

‫Dataform משתמש ב-Identity and Access Management API כדי להציג את רשימת חשבונות השירות. לשם כך נדרשת הרשאה iam.serviceAccounts.list ברמת הפרויקט.

כדי לפתור את הבעיה תוכלו לנסות אחד מהפתרונות הבאים:

  • לוחצים על Enter manually ומזינים את המזהה של חשבון השירות.
  • מבקשים מהאדמין של הפרויקט להקצות לכם את התפקיד "צפייה בחשבונות שירות" (roles/iam.serviceAccountViewer) או תפקיד אחר שכולל את ההרשאה iam.serviceAccounts.list בפרויקט.

ארגומנט לא ידוע: תגים

השגיאה הבאה מתקבלת כשגרסת Dataform CLI לא מזהה את הארגומנט tags:

Unknown argument: tags

כדי לפתור את השגיאה, מבצעים את הפעולות הבאות:

  • מעדכנים את גרסת ה-CLI ל-3.0.0 ואילך. תמיד צריך לבדוק גרסאות חדשות של חבילות בסביבה שאינה סביבת ייצור לפני שפורסים אותן בסביבת הייצור.
  • מומלץ תמיד להשתמש בגרסה העדכנית ביותר של חבילת הליבה של Dataform.
  • מציינים במפורש את גרסת החבילה ב-package.json, לדוגמה 3.0.0. אל תשתמשו באפשרויות אחרות של dependencies package.json, למשל >version.