واجهة برمجة تطبيقات المهام

توفّر واجهة برمجة تطبيقات "المهام" نقاط نهاية للمساعدة في إنشاء الإجراء الخاص بك وإدارته واختباره.

مكتبة العميل (Node.js)

على الرغم من أنه يمكنك استخدام خدمة Actions API RESTful من خلال إرسال طلبات HTTP مباشرة إلى الخادم، نوفّر مكتبة عميل تسهّل الوصول إلى نقاط النهاية من Node.js. تتيح لك مكتبة برامج واجهة برمجة تطبيقات الإجراءات إدارة الإجراء واختباره باستخدام مجموعة متنوعة من نقاط النهاية.

على سبيل المثال، يُجري الرمز أدناه طلبًا بنقطة نهاية 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);
    }

للحصول على تعليمات التثبيت والمواد المرجعية لمكتبة عميل Node.js لواجهة برمجة تطبيقات الإجراءات، يمكنك الاطّلاع على مستندات المكتبة ومرجع REST في واجهة برمجة تطبيقات الإجراءات.

المتطلّبات

تنطبق المتطلبات التالية على الطلبات التي يتم إرسالها إلى Actions API.

حجم حمولة الطلب

يجب أن يكون حجم الطلبات المقدمة إلى Actions API 10 ميغابايت أو أقل. ويشمل ذلك نقاط نهاية بث العميل، حيث يجب أن يكون حجم كل طلب في البث 10 ميغابايت أو أقل.

إذا تجاوزت حمولة البيانات 10 ميغابايت، من المفترَض أن تتلقّى خطأ 400 من خادم "حزمة تطوير البرامج (SDK) للإجراءات".

أفضل الممارسات

ننصحك بشدّة باتّباع أفضل الممارسات التالية عند استخدام Actions API.

ضبط عنوان طلب مشروع x-goog-user-project

عند إنشاء أداة أو تطبيق للمستخدمين، قد ترغب في فوترة مشروع أحد المستخدمين واستخدامه في حدود الحصة، بدلاً من مشروع العميل. ولتحديد مشروع لأغراض الفوترة والحصة، يمكنك ضبط عنوان الطلب x-goog-user-project.

القيم الصالحة رقم تعريف المشروع لمشروع حالي على Google Cloud
مثال x-goog-user-project: my-project
التفاصيل يُستخدَم المشروع المحدّد في العنوان لحدود الحصة ويتم إصدار فواتير له مقابل الرسوم المرتبطة بالطلب.

ضبط عنوان طلب وكيل المستخدم

يمكنك ضبط وكيل مستخدم مناسب باستخدام عنوان الطلب user-agent. يساعد ذلك واجهة برمجة التطبيقات في تحديد ما إذا كان مصدر الطلبات هو الشركاء.

القيود المعروفة

يوضِّح هذا القسم القيود المعروفة في Actions API.

مهلة نقاط نهاية بث البرنامج

لا ينطبق هذا التقييد إلا على طلبات HTTP التي تجريها على نقاط نهاية بث البرنامج. ولا تتأثر الطلبات المقدّمة باستخدام مكتبة العملاء بهذا القيد.

إذا كنت تستخدم طلبات HTTP لاستدعاء WritePreview أو CreateVersion أو WriteDraft، ننصحك بتنفيذ مهلة للتعامل مع الطلبات غير الناجحة.

إذا تلقيت عنوان استجابة يحدّد رمز حالة غير 200، من المفترض أن ينهي الرمز البث بعد فترة زمنية معيّنة. لا تؤثّر هذه المشكلة إلا في نقاط نهاية بث العميل. على سبيل المثال، تنتهي مهلة 5 ثوانٍ لأداة gactions التي تستخدم Actions API.