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

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

مكتبة البرامج (Node.js)

على الرغم من أنّه يمكنك استخدام خدمة Action 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 لواجهة برمجة تطبيقات الإجراءات.

المتطلبات

تنطبق المتطلبات التالية على الطلبات المقدَّمة إلى واجهة برمجة تطبيقات الإجراءات.

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

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

إذا تجاوزت حمولة البيانات 10 ميغابايت، من المفترض أن يظهر لك خطأ 400 في قسم "الإجراءات". خادم SDK.

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

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

تعيين عنوان طلب x-goog-user-project

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

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

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

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

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

يوضِّح هذا القسم القيود المعروفة في واجهة برمجة تطبيقات الإجراءات.

مهلة نقاط نهاية بث العميل

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

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

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