API לפעולות

Actions API מספק נקודות קצה (endpoints) שעוזרות ליצור, לנהל ולבדוק את הפעולה.

ספריית לקוח (Node.js)

אפשר להשתמש בשירות RESTful של Actions API על ידי שליחת בקשות HTTP ישירות לשרת, אבל אנחנו מספקים ספריית לקוח שמאפשרת לגשת בקלות לנקודות הקצה מ-Node.js. ספריית הלקוח של Actions API מאפשרת לנהל ולבדוק את הפעולה באמצעות מגוון נקודות קצה.

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

   import {ActionsSdkClient} from '@assistant/actions';
   import { promisify } from 'util';
   import * as stream from 'stream';

   const PROJECT_ID = '<PROJECT_ID>';
   const VERSION = 123;

   const projectPath = `projects/${PROJECT_ID}`;
   const versionPath = `projects/${PROJECT_ID}/versions/${VERSION}`;

    async function publishPreview(projectPath, versionPath) {
      const request = {
        parent: projectPath,
        previewSettings: {sandbox: {value: true}},
        submittedVersion: {version: versionPath}
      };

      const client = new ActionsSdkClient();
      const stream = client.writePreview(()=>{});
      stream.write(request);
      stream.end();
      const finished = promisify(stream.finished);
      await finished(stream);
    }

לקבלת הוראות להתקנה וחומר עזר של ספריית הלקוח של Actions API Node.js, אפשר לעיין בספרייה ובחומרי העזר של Actions API ל-REST.

דרישות

הדרישות הבאות חלות על בקשות שנשלחות ל-Actions API.

בקשת גודל מטען ייעודי (payload)

הגודל של בקשות שנשלחות ל-Actions API הוא 10MB או פחות. המידע הזה כולל נקודות קצה של סטרימינג של לקוחות, שבהן כל בקשה בשידור חייבת להיות בגודל של 10MB או פחות.

אם המטען הייעודי (Payload) חורג מ-10MB, אמורה להופיע שגיאה מסוג 400 בקטע 'פעולות' שרת SDK.

שיטות מומלצות

השיטות המומלצות הבאות מומלצות מאוד כאשר אתם משתמשים ב-Actions API.

הגדרת כותרת הבקשה x-goog-user-project

כאשר אתם בונים כלי או אפליקציה עבור המשתמשים שלכם, כדאי שתוודאו לפרויקט לחיוב ולשימוש במסגרת מגבלות מכסה, במקום בפרויקט הלקוח שלכם. כדי לציין פרויקט למטרות חיוב ומכסה, מגדירים את כותרת הבקשה x-goog-user-project.

ערכים חוקיים	Project ID של חשבון קיים פרויקט ב-Google Cloud
דוגמה	x-goog-user-project: my-project
פרטים	הפרויקט שצוין בכותרת משמש למגבלות מכסה ולחיוב לחיובים שמשויכים לבקשה.

הגדרת כותרת הבקשה של סוכן המשתמש

צריך להגדיר סוכן משתמש מתאים באמצעות כותרת הבקשה user-agent. הזה עוזרת ל-API לקבוע אם הבקשות מגיעות משותפים.

מגבלות ידועות

בקטע הזה מתוארות מגבלות ידועות של Actions API.

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

ההגבלה הזו חלה רק על בקשות HTTP שמבצעים בסטרימינג של לקוחות נקודות קצה (endpoints). בקשות שמבוצעות באמצעות ספריית הלקוח לא מושפעים מהגבלה זו.

אם אתם משתמשים בבקשות HTTP כדי לקרוא ל-WritePreview, ל-CreateVersion או ל-WriteDraft, אנחנו מומלץ להטמיע זמן קצוב לתפוגה כדי לטפל בבקשות שלא הפעולה הצליחה.

אם מקבלים כותרת תגובה שמציינת קוד סטטוס שאינו 200, הקוד אמור לסיים את הסטרימינג לאחר פרק זמן מסוים. הבעיה הזו משפיעה רק על נקודות קצה של סטרימינג של לקוחות. לדוגמה, הכלי gactions, שמשתמש ב-Actions API, הזמן הקצוב לתפוגה שלו הוא 5 שניות.