פתרון בעיות ב-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 זמין במאמר חיבור למאגר Git של צד שלישי.

יש חריגה ממגבלת הבו-זמניות (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. כדי לעשות זאת, צריך להחריג את מזהה לקוח ה-OAuth של Dataform בהגדרות של רמת הגישה. פרטים על החרגת אפליקציות מופיעים במאמר בנושא הגדרת רמות גישה לאפליקציות נתמכות.

כדי לקבל את מזהה הלקוח ב-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+.

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

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

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

API request error: Package installation timed out

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

אם הגדרות הגרסה מפנות אל Git commitishes, צריך לוודא שהקבצים 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. הפעלת ביצועים מתוזמנים בהפרש זמן: כשמתזמנים כמה הידורים או הפעלות של טריגרים של גרסאות, כדאי להגדיר את לוחות הזמנים שלהם ב-cron כך שיהיה ביניהם הפרש זמן, כדי לחלק את עומס הרשת. לדוגמה, אפשר להזיז את לוחות הזמנים ב-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 יש גישה לסוד.

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

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

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

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

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

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

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

Unknown argument: tags

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

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