API לפעולות

ה-Actions API מספק נקודות קצה שיעזרו לכם לבנות, לנהל ולבדוק את הפעולה.

ספריית לקוח (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, עיינו במסמכי התיעוד של הספרייה וחומר העזר בנושא REST ב-Actions API.

דרישות

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

יש לבקש גודל מטען

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

אם המטען הייעודי (payload) גדול מ-10MB, אמורה להתקבל הודעת השגיאה 400 משרת ה-Actions של SDK.

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

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

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

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

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

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

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

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

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

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

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

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

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