תזמון פוסטים ברשתות חברתיות עם REST API

הרצף המלא

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

המתכון הזה משתמש ב-REST. לקוח MCP פועל לפי הרצף המקביל, whoami → list_channels → validate_post → create_post → get_post, שמתואר במדריך ה-MCP לרשתות חברתיות.

לנסות את בדיקת הקלט עם דוגמה מוכנה להרצה

יש להוריד את בודק הקלט ל-Node.js ואת התבנית post.example.json לאותה תיקייה. הסקריפט צריך Node.js 22 ומעלה, בלי שום חבילה נוספת. כדאי לקרוא את קוד המקור שלו, ואז לספק מפתח גישה קיים של Hub דרך משתני הסביבה הסודיים שלך, בשם MELLOW_HUB_KEY.

לבדיקה הזו מספיקות ההרשאות channels:read ו-posts:read. בהגדרות הגישה של Hub יש לבחור רק את הערוצים שבכוונתך להשתמש בהם. להצגת רשימת הערוצים מספיקה ההרשאה הראשונה. בדיקת הקלט הזו לא דורשת הרשאת פרסום או מנוי.

node mellow-hub-check.mjs --channels
# יש להחליף את מזהי הערוצים ואת ה-URL של המדיה בקובץ post.example.json.
node mellow-hub-check.mjs post.example.json

הסקריפט בודק אילו ערוצים זמינים למפתח הגישה, שולח את קובץ ה-JSON הערוך שלך לנקודת הקצה של Mellow Hub לאימות, שדורשת הזדהות, ומדפיס את הבעיות החוסמות ואת ההערות. קוד היציאה הוא 0 כשבדיקות הקלט האלה עוברות, 1 כשיש בעיות בקלט, או 2 בכשל של קובץ, הרשאה או חיבור, או בתגובה לא צפויה. גם תגובת HTTP 200 עם ok: false נחשבת לכישלון בבדיקה.

הסקריפט לא יוצר פוסט, לא מוריד מדיה ולא שולח שום בקשה לרשת חברתית. גם כשהבדיקה עוברת, היא לא מוודאת את משך הקובץ, את יחס הרוחב-גובה, את ההרשאה הסופית של החשבון או את הפרסום עצמו. הקוד שמורידים נבדק מול נתוני בדיקה מבודדים; זה לא תיעוד של פרסום חי אצל לקוח אמיתי. לבקשות ה-curl שבהמשך, יש לשמור את הקובץ הערוך בשם post.json.

1. בדיקת החשבון ומפתח הגישה

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

curl --fail-with-body https://www.mellow.world/api/hub/v1/whoami \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

curl --fail-with-body https://www.mellow.world/api/hub/v1/channels \
  -H "Authorization: Bearer $MELLOW_HUB_KEY"

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

2. תיאור הפוסט האמיתי

יש לשמור את המבנה הבא בשם post.json ולהחליף בו את שני מזהי הערוצים, את כתובת המדיה לדוגמה, את הטקסט ואת התאריך לדוגמה. יש לציין במפורש היסט של אזור זמן לפי ISO 8601, או Z של UTC; חותמת הזמן מייצגת רגע מסוים, לא את השעון המקומי של הקורא. התאריך בשנת 2030 בדוגמה נבחר בכוונה להמחשה בלבד.

{
  "caption": "A short look at how this piece was made.",
  "channels": [
    "spc_your_instagram_channel",
    "spc_your_youtube_channel"
  ],
  "media": [
    "https://cdn.example.com/your-video.mp4"
  ],
  "scheduledAt": "2030-01-15T10:00:00Z",
  "options": {
    "instagram": {
      "placement": "reels"
    },
    "youtube": {
      "title": "How this piece was made",
      "privacyStatus": "public"
    }
  }
}

הרשת מורידה את המדיה בזמן הפרסום, ולכן ה-URL האמיתי ב-HTTPS צריך להישאר נגיש גם אז. קובץ מקומי פרטי או URL חתום שפג תוקפו לא יעבדו. בדוגמה הזו יש ל-YouTube כותרת נפרדת משלה, ול-Instagram נבחר המיקום Reels. זמינות הפורמטים עדיין תלויה בחשבונות המחוברים שלך ובספק.

3. אימות בלי לפרסם

curl --fail-with-body https://www.mellow.world/api/hub/v1/validate \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @post.json

יש לבדוק בתגובה את ok, את issues ואת notes. לפני שממשיכים, יש לתקן כל בעיה חוסמת. האימות יכול להחזיר HTTP 200 עם ok: false, ולכן לא מספיק לבדוק רק את סטטוס ה-HTTP. נקודת הקצה, שדורשת הזדהות, בודקת גם את הבעלות שלך בפועל על הערוצים, ולא רק את כללי הקלט.

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

4. יצירה פעם אחת, ניסיון חוזר באותה דרך

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

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

curl --fail-with-body https://www.mellow.world/api/hub/v1/posts \
  -H "Authorization: Bearer $MELLOW_HUB_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: studio-process-video-slot-001" \
  --data-binary @post.json

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

5. קריאת התוצאה בכל יעד

יש לשמור את ה-post.id שהוחזר ולשלוף את הפוסט עם GET /api/hub/v1/posts/{id}, עם אותה כותרת הרשאה. כדאי לבדוק כל רשומה ב-targets ואת ה-URL הציבורי שלה. פוסט לכמה רשתות יכול להסתיים בתוצאה חלקית: יעד אחד יכול להצליח בזמן שיעד אחר נכשל.

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

שחזור אחרי פקיעת זמן המתנה או פרסום חלקי

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

התגובה לבקשת היצירה אבדה

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

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

יעד אחד נכשל, ובאחר הפוסט כבר פורסם

לפני שמכינים שחזור, יש לקרוא את targets. לדוגמה, אם ב-Instagram הסטטוס הוא published וב-YouTube הוא failed, יש לתקן את הבעיה שדווחה ב-YouTube ולאמת גוף בקשה חדש שכולל רק את ערוץ ה-YouTube הזה. שחזור מכוון משתמש במפתח חדש, למשל studio-process-video-slot-001-youtube-recovery-1. את מזהה הפוסט החדש שלו יש לשמור לצד המשימה המקורית. הרשאות הערוצים הרגילות, מצב האישור ומכסת הפרסומים עדיין חלים.

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

שאלות שעולות באינטגרציות אמיתיות

אפשר להשתמש בכיתוב אחר ברשת אחת?

כן. רשומה ב-perChannel, תחת מזהה הערוץ האמיתי, מחליפה את הכיתוב או את המדיה של אותו ערוץ. שדות שחלים על כל הפלטפורמה שייכים ל-options. דוגמאות מפורטות אפשר למצוא בחומר העזר של Hub.

האם סוכן יכול לחבר את החשבונות שלי ברשתות החברתיות בעצמו?

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

האם בקשה אחת צורכת פרסום אחד מהתוכנית שלי?

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