הרצות

רשומת הרצה מייצגת הרצה אחת של תהליך שלם. היא מתעדת את הסטטוס של ההרצה, כמה רכיבים כבר הסתיימו, כמה קרדיטים הוצאו ואת המצב והתוצאה של כל רכיב, והיא מקבצת את המשימות שההרצה יצרה, אחת לכל רכיב AI. הנתיב POST /v1/workflows/:id/run מחזיר executionId, ובעזרת נקודות הקצה של רשומות ההרצה אפשר לבדוק את המצב של ההרצה הזו עד שהיא מסתיימת.

נקודות קצה

שתי נקודות הקצה האחרונות שייכות להרצות שמתחילות עם POST /v1/api/run. הן מתוארות בדף ה-API תהליכים, בסעיף הרצת תהליך עם ערכי קלט חדשים.

קריאת הרצה

curl -s https://app.nodaro.ai/v1/workflow-executions/3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b \
  -H "Authorization: Bearer $NODARO_API_KEY"

const { data } = await client.executions.get(executionId)
console.log(data.status, `${data.completedNodes}/${data.totalNodes}`)

nodaro executions get 3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b --json

{
  "data": {
    "id": "3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b",
    "workflowId": "8c2d7f1e-3a4b-4c5d-9e6f-7a8b9c0d1e2f",
    "status": "running",
    "triggerType": "manual",
    "totalNodes": 4,
    "completedNodes": 2,
    "failedNodes": 0,
    "totalCreditsUsed": 45,
    "errorMessage": null,
    "nodeStates": {
      "text-prompt-1": { "status": "completed", "output": { "text": "a knight on a hill at dawn" } },
      "generate-image-1": { "status": "completed", "output": { "imageUrl": "https://…/knight.png" } },
      "generate-video-1": { "status": "running" },
      "add-captions-1": { "status": "pending" }
    },
    "completedAt": null
  }
}

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

סטטוסים של הרצה

מצבי הרכיבים

לכל ערך ב-nodeStates יש status: pending, running, completed, failed או skipped. ברכיב שנכשל יש גם error. המצב של רכיב שדולג כי שום דבר לא הגיע לקלט שלו בהרצה הזו הוא { "status": "skipped", "skipReason": "empty_input" }. ברכיב שדולג בגלל מסלול לא פעיל של רכיב נתב אין skipReason. ראו בדף ה-API הרצות שלא מוצאות שום דבר חדש.

התוצאה של רכיב שהסתיים נמצאת ב-output. המפתחות נקבעים לפי הפלט של הרכיב: חפשו url, imageUrl, videoUrl, audioUrl, resultUrl או text, בסדר הזה.

גם ברכיב שנכשל יכול להיות output, כשההרצה שמרה תוצאה מובנית. כרגע זה קורה ברכיבים שבונים סצנות תלת־ממד: סצנה שהבדיקה החזותית שלה נכשלה גם אחרי כל התיקונים עדיין מפרסמת טיוטה, והרכיב נכשל כשהטיוטה הזו נמצאת ב-output.plan. מכאן נובעים שני כללים:

• בדקו אם השדה קיים, לא את הסטטוס. לרכיב בסטטוס pending או running אף פעם אין output, וסוגי רכיבים אחרים עשויים לשמור תוצאות בעתיד.
• גם כש-output קיים, זו לא הצלחה. הרכיב נכשל; הוא רק שמר משהו.

ה-SDK מייצא את הפונקציה nodeStateMayCarryOutput(status), שמחזירה true בסטטוסים completed ו-failed, ואת אותו זוג גם כקבוע OUTPUT_BEARING_NODE_STATUSES.

המתנה לסיום הרצה

בדקו את הסטטוס כל 2–5 שניות, עד שהוא סופי:

const { executionId } = await client.workflows.run(workflowId)

const final = ['completed', 'failed', 'cancelled', 'timed_out', 'discarded']
while (true) {
  const { data } = await client.executions.get(executionId)
  console.log(`${data.completedNodes}/${data.totalNodes} nodes done`)
  if (final.includes(data.status)) {
    if (data.status !== 'completed') throw new Error(`Run ${data.status}: ${data.errorMessage ?? 'no message'}`)
    console.log(`Done. Used ${data.totalCreditsUsed} credits.`)
    break
  }
  await new Promise((r) => setTimeout(r, 2_000))
}

while true; do
  STATUS=$(curl -s -H "Authorization: Bearer $NODARO_API_KEY" \
    "https://app.nodaro.ai/v1/workflow-executions/$EXEC" | jq -r .data.status)
  echo "Status: $STATUS"
  case "$STATUS" in completed|failed|cancelled|timed_out|discarded) break;; esac
  sleep 3
done

nodaro executions get 3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b --watch

עם --watch, ה-CLI בודק את הסטטוס עד שההרצה מסתיימת, ויוצא עם קוד היציאה 0 כשההרצה מצליחה, 2 כשההרצה נכשלה ו-130 כשהיא בוטלה. עם --json, ה-CLI מדפיס את המטען ויוצא כרגיל, ולכן בדקו את .status בעצמכם.

הנתיב GET /v1/workflow-executions/:id/stream שולח את אותו מצב של ההרצה כאירועי שרת (SSE) כל עוד ההרצה בעיצומה, וחלים עליו אותם כללים לגבי ה-output של הרכיבים כמו על הקריאה שלמעלה. ברוב האינטגרציות, תשאול הוא הבחירה הפשוטה יותר.

רשימת ההרצות של תהליך

הנתיב GET /v1/workflows/:id/executions מחזיר את ההרצות של תהליך בעמודים, בצורה { data, nextCursor }. ברשימה מופיעות, לצד ההרצות המלאות של התהליך, גם המשימות העצמאיות של רכיב יחיד בתהליך הזה.

curl -s "https://app.nodaro.ai/v1/workflows/$WORKFLOW_ID/executions?limit=20&status=completed" \
  -H "Authorization: Bearer $NODARO_API_KEY"

const { data, nextCursor } = await client.executions.listForWorkflow(workflowId, {
  limit: 20,
  status: 'completed',
})

ביטול הרצה

הנתיב POST /v1/workflow-executions/:id/cancel עוצר הרצה. השדה האופציונלי mode בגוף הבקשה קובע מה קורה לרכיבים שכבר רצים:

התגובה היא { "success": true }.

curl -s -X POST https://app.nodaro.ai/v1/workflow-executions/$EXEC/cancel \
  -H "Authorization: Bearer $NODARO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "after_current"}'

await client.executions.cancel(executionId)                           // now
await client.executions.cancel(executionId, { mode: 'after_current' }) // after running nodes
await client.executions.cancel(executionId, { mode: 'discard' })       // stop scheduling

nodaro executions cancel 3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b                # now
nodaro executions cancel 3f9e2b1a-7c6d-4e5f-8a9b-0c1d2e3f4a5b --mode stopping # after running nodes

כדי לעצור יצירה אחת ולא הרצה שלמה, בטלו את המשימה שלה: ראו בדף ה-API משימות.

הרצות ומשימות

כל רכיב AI בהרצה יוצר משימה, והתוצאה של כל רכיב מופיעה ב-nodeStates כשהמשימה שלו מסתיימת. בדקו את רשומת ההרצה כדי לדעת מה המצב של ההרצה כולה. בדקו משימה כדי לקבל את הפרטים של יצירה אחת: ה-error_hint שלה, ה-credit_status שלה, או כל מה שנשלח למודל ב-input_data.

הרצות שטריגר מתחיל, כגון קריאה לרכיב טריגר Webhook או הרצה שרכיב טריגר מתוזמן מתחיל, מקבלות גם הן רשומת הרצה, עם triggerType שערכו webhook או schedule. ראו את דף ה-API Webhooks.