ساختن رزروها (Dialogflow)

این راهنما شما را در فرایند توسعه پروژه «کنش‌ها» که از Orders API برای رزرو کردن استفاده می‌کند همراهی می‌کند.

جریان تراکنش

وقتی پروژه «کنش‌های» شما رزروها را مدیریت می‌کند، از جریان زیر استفاده می‌کند:

  1. اعتبارسنجی الزامات تراکنش (اختیاری) - از کمک‌کننده الزامات تراکنش در ابتدای مکالمه استفاده کنید تا مطمئن شوید کاربر قادر به انجام تراکنش است.
  2. ایجاد سفارش - کاربر را در فرایند «جمع‌آوری سبد خرید» راهنمایی کنید تا جزئیات رزرو خود را ایجاد کند.
  3. پیشنهاد سفارش - وقتی «سبد خرید» تکمیل شد، «سفارش» رزرو را به کاربر پیشنهاد دهید تا بتواند درست بودن آن را تأیید کند. اگر رزرو تأیید شود، پاسخی با جزئیات رزرو دریافت خواهید کرد.
  4. نهایی کردن سفارش و ارسال رسید - با تأیید سفارش، سیستم رزرو خود را به‌روز کنید و رسیدی برای کاربر ارسال کنید.
  5. ارسال به‌روزرسانی‌های سفارش - درطول دوره رزرو، با ارسال درخواست‌های PATCH به Orders API، به‌روزرسانی‌های وضعیت رزرو را به کاربر ارائه دهید.

محدودیت‌ها و رهنمودهای بازبینی

به‌خاطر داشته باشید که خط‌مشی‌های دیگری برای «کنش‌هایی» که از تراکنش‌ها و Orders API استفاده می‌کنند اعمال می‌شود. بررسی «کنش‌ها» با تراکنش‌ها ممکن است تا شش هفته طول بکشد، بنابراین این زمان را هنگام برنامه‌ریزی زمان‌بندی انتشار خود درنظر بگیرید. برای تسهیل فرایند بازبینی، قبل‌از ارسال «کنش» برای بازبینی، مطمئن شوید که از خط‌مشی‌ها و دستورالعمل‌های تراکنش‌ها پیروی می‌کنید.

فقط در کشورهای زیر می‌توانید «کنش‌هایی» را که از Orders API استفاده می‌کنند مستقر کنید:

استرالیا
برزیل
کانادا
اندونزی
ژاپن
مکزیک
قطر
روسیه
سنگاپور
سوئیس
تایلند
ترکیه
پادشاهی متحد (UK)
ایالات متحده

ساختن پروژه

برای نمونه‌های گسترده مکالمه‌های تراکنشی، نمونه‌های تراکنش ما را در Node.js و Java مشاهده کنید.

راه‌اندازی پروژه

هنگام ایجاد «کنش»، باید مشخص کنید که می‌خواهید تراکنش‌ها را در کنسول Actions انجام دهید. همچنین، اگر از کتابخانه کارخواه Node.JS استفاده می‌کنید، تحقق را طوری راه‌اندازی کنید که از جدیدترین نسخه Orders API استفاده کند.

برای راه‌اندازی پروژه و تحقق، کارهای زیر را انجام دهید:

  1. پروژه جدیدی ایجاد کنید یا پروژه موجودی را وارد کنید.
  2. به استقرار > اطلاعات دایرکتوری بروید.
  3. در بخش اطلاعات بیشتر > تراکنش‌ها > چارگوش کنار «آیا «کنش‌های» شما از Transactions API برای انجام تراکنش‌های کالاهای فیزیکی استفاده می‌کند؟» را علامت بزنید.

  4. اگر از کتابخانه کارخواه Node.JS برای ساختن تحقق «کنش» خود استفاده می‌کنید، کد تحقق خود را باز کنید و اعلامیه برنامه خود را به‌روز کنید تا پرچم ordersv3 را روی true تنظیم کنید. تکه‌کد زیر نمونه‌ای از اعلامیه برنامه برای «سفارش‌ها» نسخه ۳ را نشان می‌دهد.

Node.js

const {dialogflow} = require('actions-on-google');
let app = dialogflow({
  clientId, // If using account linking
  debug: true,
  ordersv3: true,
});

Node.js

const {actionssdk} = require('actions-on-google');
let app = actionssdk({
  clientId, // If using account linking
  debug: true,
  ordersv3: true,
});

۱. اعتبارسنجی الزامات تراکنش (اختیاری)

تجربه کاربر

به‌محض اینکه کاربر نشان داد که می‌خواهد رزرو را تنظیم کند، توصیه می‌کنیم قصد actions.intent.TRANSACTION_REQUIREMENTS_CHECK را راه‌اندازی کنید تا مطمئن شوید که می‌تواند درخواست رزرو کند. برای مثال، وقتی «کنش» شما فراخوانده می‌شود، ممکن است بپرسد: «می‌خواهید صندلی رزرو کنید؟» اگر کاربر گفت «بله»، باید فوراً این قصد را درخواست کنید. این کار تضمین می‌کند که آن‌ها می‌توانند ادامه دهند و به آن‌ها فرصت می‌دهد تا هرگونه تنظیماتی را که مانع ادامه تراکنش می‌شود اصلاح کنند.

درخواست بررسی الزامات تراکنش‌ها منجر به یکی از نتایج زیر می‌شود:

  • اگر الزامات برآورده شود، اجرای شما هدفی با شرایط موفقیت دریافت می‌کند و می‌توانید سفارش کاربر را بسازید.
  • اگر یک یا چند مورد از الزامات برآورده نشود، تحقق شما قصد را با شرایط ناموفق دریافت می‌کند. در این حالت، مکالمه را پایان دهید یا از جریان رزرو خارج شوید.

    اگر کاربر بتواند خطا را برطرف کند، به‌طور خودکار از او خواسته می‌شود آن مشکلات را در دستگاهش حل کند. اگر مکالمه در سطحی که فقط صدا دارد (مثل بلندگوی هوشمند) انجام می‌شود، به تلفن کاربر منتقل می‌شود.

تحویل سفارشات

برای اطمینان از اینکه کاربر الزامات تراکنش را برآورده می‌کند، تکمیل هدف actions.intent.TRANSACTION_REQUIREMENTS_CHECK را با شیء TransactionRequirementsCheckSpec درخواست کنید.

بررسی کردن الزامات

بررسی کنید که آیا کاربر با کتابخانه مشتری الزامات رزرو را برآورده می‌کند یا نه:

Node.js
conv.ask(new TransactionRequirements());
جاوا
return getResponseBuilder(request)
    .add("Placeholder for transaction requirements text")
    .add(new TransactionRequirements())
    .build();
Dialogflow JSON

توجه داشته باشید که JSON زیر پاسخ وب‌قلاب را شرح می‌دهد.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "systemIntent": {
        "intent": "actions.intent.TRANSACTION_REQUIREMENTS_CHECK",
        "data": {
          "@type": "type.googleapis.com/google.actions.transactions.v3.TransactionRequirementsCheckSpec"
        }
      }
    }
  }
}
قالب JSON کیت توسعه نرم‌افزار Actions

توجه داشته باشید که JSON زیر پاسخ وب‌قلاب را شرح می‌دهد.

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TRANSACTION_REQUIREMENTS_CHECK",
          "inputValueData": {
            "@type": "type.googleapis.com/google.actions.transactions.v3.TransactionRequirementsCheckSpec"
          }
        }
      ]
    }
  ]
}
دریافت نتیجه بررسی الزامات

پس‌از اینکه «دستیار» هدف را برآورده کرد، درخواستی با هدف actions.intent.TRANSACTION_REQUIREMENTS_CHECK و نتیجه بررسی به برآورده‌سازی شما ارسال می‌کند.

برای رسیدگی صحیح به این درخواست، هدف Dialogflow را که توسط رویداد actions_intent_TRANSACTION_REQUIREMENTS_CHECK راه‌اندازی شده است اعلام کنید. وقتی فعال شد، این قصد را در تحقق خود مدیریت کنید:

Node.js
const arg = conv.arguments.get('TRANSACTION_REQUIREMENTS_CHECK_RESULT');
if (arg && arg.resultType === 'CAN_TRANSACT') {
  // Normally take the user through cart building flow
  conv.ask(`Looks like you're good to go!`);
} else {
  conv.close('Transaction failed.');
}
جاوا
Argument transactionCheckResult = request
    .getArgument("TRANSACTION_REQUIREMENTS_CHECK_RESULT");
boolean result = false;
if (transactionCheckResult != null) {
  Map<String, Object> map = transactionCheckResult.getExtension();
  if (map != null) {
    String resultType = (String) map.get("resultType");
    result = resultType != null && resultType.equals("CAN_TRANSACT");
  }
}
ResponseBuilder responseBuilder = getResponseBuilder(request);
if (result) {
  responseBuilder.add("Looks like you're good to go! Now say 'confirm transaction'");
} else {
  responseBuilder.add("Transaction failed");
}
return responseBuilder.build();
Dialogflow JSON

توجه داشته باشید که JSON زیر درخواست وب‌قلاب را شرح می‌دهد.

{
  "responseId": "",
  "queryResult": {
    "queryText": "",
    "action": "",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [],
    "intent": {
      "name": "reservation_transaction_check_complete_df",
      "displayName": "reservation_transaction_check_complete_df"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": ""
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [],
          "intent": "",
          "arguments": [
            {
              "extension": {
                "@type": "type.googleapis.com/google.transactions.v3.TransactionRequirementsCheckResult",
                "resultType": "CAN_TRANSACT"
              },
              "name": "TRANSACTION_REQUIREMENTS_CHECK_RESULT"
            }
          ]
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            },
            {
              "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
            },
            {
              "name": "actions.capability.WEB_BROWSER"
            }
          ]
        }
      ]
    }
  },
  "session": ""
}
قالب JSON کیت توسعه نرم‌افزار Actions

توجه داشته باشید که JSON زیر درخواست وب‌قلاب را شرح می‌دهد.

{
  "user": {},
  "device": {},
  "surface": {
    "capabilities": [
      {
        "name": "actions.capability.SCREEN_OUTPUT"
      },
      {
        "name": "actions.capability.AUDIO_OUTPUT"
      },
      {
        "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
      },
      {
        "name": "actions.capability.WEB_BROWSER"
      }
    ]
  },
  "conversation": {},
  "inputs": [
    {
      "rawInputs": [],
      "intent": "reservation_transaction_check_complete_asdk",
      "arguments": [
        {
          "extension": {
            "@type": "type.googleapis.com/google.transactions.v3.TransactionRequirementsCheckResult",
            "resultType": "CAN_TRANSACT"
          },
          "name": "TRANSACTION_REQUIREMENTS_CHECK_RESULT"
        }
      ]
    }
  ],
  "availableSurfaces": [
    {
      "capabilities": [
        {
          "name": "actions.capability.SCREEN_OUTPUT"
        },
        {
          "name": "actions.capability.AUDIO_OUTPUT"
        },
        {
          "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
        },
        {
          "name": "actions.capability.WEB_BROWSER"
        }
      ]
    }
  ]
}

۲. ساختن سفارش

تجربه کاربر

وقتی اطلاعات کاربر موردنیازتان را دریافت کردید، تجربه «مونتاژ سبد خرید» را بسازید که کاربر را برای ایجاد رزرو راهنمایی می‌کند. هر «کنش» جریان مونتاژ سبد خرید کمی متفاوتی خواهد داشت که برای سرویس آن مناسب است.

در تجربه مونتاژ سبد خرید پایه، کاربر گزینه‌هایی را از فهرست انتخاب می‌کند تا به رزرو خود اضافه کند، اگرچه می‌توانید مکالمه را برای ساده کردن تجربه کاربر طراحی کنید. برای مثال، تجربه مونتاژ سبد خریدی بسازید که به کاربر امکان می‌دهد با یک سؤال ساده بله یا خیر، رزرو ماهانه را زمان‌بندی کند. همچنین می‌توانید کارت فهرست یا گردونه‌ای از رزروهای «توصیه‌شده» را به کاربر ارائه دهید.

توصیه می‌کنیم از پاسخ‌های غنی برای ارائه گزینه‌های کاربر به‌صورت بصری استفاده کنید، اما مکالمه را نیز طوری طراحی کنید که کاربر بتواند سبد خرید خود را فقط بااستفاده از صدای خود بسازد. برای اطلاع از برخی روال‌های مطلوب و نمونه‌های تجربه‌های مونتاژ سبد خرید، به دستورالعمل‌های طراحی تراکنش‌ها مراجعه کنید.

تحویل سفارشات

درطول مکالمه، جزئیات رزروی را که کاربر می‌خواهد خریداری کند جمع‌آوری کنید و سپس شیء Order را بسازید.

Order شما باید حداقل حاوی موارد زیر باشد:

  • buyerInfo - اطلاعات مربوط به کاربری که رزرو را زمان‌بندی می‌کند.
  • transactionMerchant - اطلاعات مربوط به تاجری که رزرو را تسهیل می‌کند.
  • contents - جزئیات واقعی رزرو به‌عنوان lineItems فهرست شده است.

برای ساختن سبد خریدتان، به سند پاسخ Order مراجعه کنید. توجه داشته باشید که ممکن است لازم باشد فیلدهای مختلفی را بسته به رزرو اضافه کنید.

کد نمونه زیر سفارش رزرو کامل را نشان می‌دهد، ازجمله فیلدهای اختیاری:

Node.js
app.intent('build_reservation_df', (conv) => {
  const now = new Date().toISOString();
  const order = {
    createTime: now,
    lastUpdateTime: now,
    merchantOrderId: 'UNIQUE_ORDER_ID',
    userVisibleOrderId: 'USER_VISIBLE_ORDER_ID',
    transactionMerchant: {
      id: 'https://www.example.com',
      name: 'Example Merchant',
    },
    contents: {
      lineItems: [
        {
          id: 'LINE_ITEM_ID',
          name: 'Dinner reservation',
          description: 'A world of flavors all in one destination.',
          reservation: {
            status: 'PENDING',
            userVisibleStatusLabel: 'Reservation is pending.',
            type: 'RESTAURANT',
            reservationTime: {
              timeIso8601: '2020-01-16T01:30:15.01Z',
            },
            userAcceptableTimeRange: {
              timeIso8601: '2020-01-15/2020-01-17',
            },
            partySize: 6,
            staffFacilitators: [
              {
                name: 'John Smith',
              },
            ],
            location: {
              zipCode: '94086',
              city: 'Sunnyvale',
              postalAddress: {
                regionCode: 'US',
                postalCode: '94086',
                administrativeArea: 'CA',
                locality: 'Sunnyvale',
                addressLines: [
                  '222, Some other Street',
                ],
              },
            },
          },
        },
      ],
    },
    buyerInfo: {
      email: 'janedoe@gmail.com',
      firstName: 'Jane',
      lastName: 'Doe',
      displayName: 'Jane Doe',
    },
    followUpActions: [
      {
        type: 'VIEW_DETAILS',
        title: 'View details',
        openUrlAction: {
          url: 'https://example.com',
        },
      },
      {
        type: 'CALL',
        title: 'Call us',
        openUrlAction: {
          url: 'tel:+16501112222',
        },
      },
      {
        type: 'EMAIL',
        title: 'Email us',
        openUrlAction: {
          url: 'mailto:person@example.com',
        },
      },
    ],
    termsOfServiceUrl: 'https://www.example.com',
  };
جاوا
private static OrderV3 createOrder() {
  // Transaction Merchant
  MerchantV3 transactionMerchant = new MerchantV3()
      .setId("http://www.example.com")
      .setName("Example Merchant");

  // Line Item

  // Reservation Item Extension
  ReservationItemExtension reservationItemExtension = new ReservationItemExtension()
      .setStatus("PENDING")
      .setUserVisibleStatusLabel("Reservation pending.")
      .setType("RESTAURANT")
      .setReservationTime(new TimeV3()
          .setTimeIso8601("2020-01-16T01:30:15.01Z"))
      .setUserAcceptableTimeRange(new TimeV3()
          .setTimeIso8601("2020-01-15/2020-01-17"))
      .setPartySize(6)
      .setStaffFacilitators(Collections.singletonList(new StaffFacilitator()
          .setName("John Smith")))
      .setLocation(new Location()
          .setZipCode("94086")
          .setCity("Sunnyvale")
          .setPostalAddress(new PostalAddress()
              .setRegionCode("US")
              .setPostalCode("94086")
              .setAdministrativeArea("CA")
              .setLocality("Sunnyvale")
              .setAddressLines(
                  Collections.singletonList("222, Some other Street"))));

  LineItemV3 lineItem = new LineItemV3()
      .setId("LINE_ITEM_ID")
      .setName("Dinner reservation")
      .setDescription("A world of flavors all in one destination.")
      .setReservation(reservationItemExtension);

  // Order Contents
  OrderContents contents = new OrderContents()
      .setLineItems(Collections.singletonList(lineItem));

  // User Info
  UserInfo buyerInfo = new UserInfo()
      .setEmail("janedoe@gmail.com")
      .setFirstName("Jane")
      .setLastName("Doe")
      .setDisplayName("Jane Doe");

  // Follow up actions
  Action viewDetails = new Action()
      .setType("VIEW_DETAILS")
      .setTitle("View details")
      .setOpenUrlAction(new OpenUrlAction()
          .setUrl("https://example.com"));

  Action call = new Action()
      .setType("CALL")
      .setTitle("Call us")
      .setOpenUrlAction(new OpenUrlAction()
          .setUrl("tel:+16501112222"));

  Action email = new Action()
      .setType("EMAIL")
      .setTitle("Email us")
      .setOpenUrlAction(new OpenUrlAction()
          .setUrl("mailto:person@example.com"));

  // Terms of service and order note
  String termsOfServiceUrl = "https://example.com";

  String now = Instant.now().toString();

  OrderV3 order = new OrderV3()
      .setCreateTime(now)
      .setLastUpdateTime(now)
      .setMerchantOrderId("UNIQUE_ORDER_ID")
      .setUserVisibleOrderId("UNIQUE_USER_VISIBLE_ORDER_ID")
      .setTransactionMerchant(transactionMerchant)
      .setContents(contents)
      .setBuyerInfo(buyerInfo)
      .setFollowUpActions(Arrays.asList(
          viewDetails,
          call,
          email
      ))
      .setTermsOfServiceUrl(termsOfServiceUrl);

  return order;
}
JSON

توجه داشته باشید که JSON زیر پاسخ وب‌قلاب را شرح می‌دهد.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "systemIntent": {
        "intent": "actions.intent.TRANSACTION_DECISION",
        "data": {
          "@type": "type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec",
          "order": {
            "createTime": "2019-07-17T18:25:30.182Z",
            "lastUpdateTime": "2019-07-17T18:25:30.182Z",
            "merchantOrderId": "UNIQUE_ORDER_ID",
            "userVisibleOrderId": "USER_VISIBLE_ORDER_ID",
            "transactionMerchant": {
              "id": "https://www.example.com",
              "name": "Example Merchant"
            },
            "contents": {
              "lineItems": [
                {
                  "id": "LINE_ITEM_ID",
                  "name": "Dinner reservation",
                  "description": "A world of flavors all in one destination.",
                  "reservation": {
                    "status": "PENDING",
                    "userVisibleStatusLabel": "Reservation is pending.",
                    "type": "RESTAURANT",
                    "reservationTime": {
                      "timeIso8601": "2020-01-16T01:30:15.01Z"
                    },
                    "userAcceptableTimeRange": {
                      "timeIso8601": "2020-01-15/2020-01-17"
                    },
                    "partySize": 6,
                    "staffFacilitators": [
                      {
                        "name": "John Smith"
                      }
                    ],
                    "location": {
                      "zipCode": "94086",
                      "city": "Sunnyvale",
                      "postalAddress": {
                        "regionCode": "US",
                        "postalCode": "94086",
                        "administrativeArea": "CA",
                        "locality": "Sunnyvale",
                        "addressLines": [
                          "222, Some other Street"
                        ]
                      }
                    }
                  }
                }
              ]
            },
            "buyerInfo": {
              "email": "janedoe@gmail.com",
              "firstName": "Jane",
              "lastName": "Doe",
              "displayName": "Jane Doe"
            },
            "followUpActions": [
              {
                "type": "VIEW_DETAILS",
                "title": "View details",
                "openUrlAction": {
                  "url": "https://example.com"
                }
              },
              {
                "type": "CALL",
                "title": "Call us",
                "openUrlAction": {
                  "url": "tel:+16501112222"
                }
              },
              {
                "type": "EMAIL",
                "title": "Email us",
                "openUrlAction": {
                  "url": "mailto:person@example.com"
                }
              }
            ],
            "termsOfServiceUrl": "https://www.example.com"
          },
          "orderOptions": {
            "requestDeliveryAddress": false,
            "userInfoOptions": {
              "userInfoProperties": [
                "EMAIL"
              ]
            }
          },
          "presentationOptions": {
            "actionDisplayName": "RESERVE"
          }
        }
      }
    }
  }
}

۳. پیشنهاد دادن سفارش

سفارش رزرو را به کاربر ارائه دهید تا آن را تأیید یا رد کند. قصد actions.intent.TRANSACTION_DECISION را درخواست کنید و Order را که ساخته‌اید ارائه دهید.

تجربه کاربر

وقتی قصد actions.intent.TRANSACTION_DECISION را درخواست می‌کنید، «دستیار» تجربه‌ای داخلی را آغاز می‌کند که در آن Order مستقیماً در «کارت پیش‌نمایش سبد خرید» ارائه می‌شود. کاربر می‌تواند بگوید «زمان‌بندی رزرو»، تراکنش را رد کند، یا درخواست کند جزئیات رزرو تغییر کند.

کاربر ممکن است در این مرحله درخواست تغییر در سفارش را نیز داشته باشد. در این حالت، باید مطمئن شوید که پس‌از تکمیل تجربه مونتاژ سبد خرید، تحقق شما می‌تواند درخواست‌های تغییر سفارش را مدیریت کند.

تحویل سفارشات

وقتی قصد actions.intent.TRANSACTION_DECISION را درخواست می‌کنید، TransactionDecision ایجاد کنید که حاوی Order و orderOptions باشد

کد زیر نمونه‌ای از TransactionsDecision را برای سفارش نشان می‌دهد:

Node.js
conv.ask(new TransactionDecision({
  orderOptions: {
    requestDeliveryAddress: 'false',
  },
  presentationOptions: {
    actionDisplayName: 'RESERVE',
  },
  order: order,
}));
جاوا
// Create order options
OrderOptionsV3 orderOptions = new OrderOptionsV3()
    .setRequestDeliveryAddress(false)
    .setUserInfoOptions(new UserInfoOptions()
        .setUserInfoProperties(Collections.singletonList("EMAIL")));

// Create presentation options
PresentationOptionsV3 presentationOptions = new PresentationOptionsV3()
    .setActionDisplayName("RESERVE");

// Ask for transaction decision
return getResponseBuilder(request)
    .add("Placeholder for transaction decision text")
    .add(new TransactionDecision()
        .setOrder(order)
        .setOrderOptions(orderOptions)
        .setPresentationOptions(presentationOptions)
    )
    .build();
Dialogflow JSON

توجه داشته باشید که JSON زیر پاسخ وب‌قلاب را شرح می‌دهد.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "systemIntent": {
        "intent": "actions.intent.TRANSACTION_DECISION",
        "data": {
          "@type": "type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec",
          "orderOptions": {
            "requestDeliveryAddress": "false"
          },
          "presentationOptions": {
            "actionDisplayName": "RESERVE"
          },
          "order": {
            "createTime": "2019-07-17T18:25:30.184Z",
            "lastUpdateTime": "2019-07-17T18:25:30.184Z",
            "merchantOrderId": "UNIQUE_ORDER_ID",
            "userVisibleOrderId": "USER_VISIBLE_ORDER_ID",
            "transactionMerchant": {
              "id": "https://www.example.com",
              "name": "Example Merchant"
            },
            "contents": {
              "lineItems": [
                {
                  "id": "LINE_ITEM_ID",
                  "name": "Dinner reservation",
                  "description": "A world of flavors all in one destination.",
                  "reservation": {
                    "status": "PENDING",
                    "userVisibleStatusLabel": "Reservation is pending.",
                    "type": "RESTAURANT",
                    "reservationTime": {
                      "timeIso8601": "2020-01-16T01:30:15.01Z"
                    },
                    "userAcceptableTimeRange": {
                      "timeIso8601": "2020-01-15/2020-01-17"
                    },
                    "partySize": 6,
                    "staffFacilitators": [
                      {
                        "name": "John Smith"
                      }
                    ],
                    "location": {
                      "zipCode": "94086",
                      "city": "Sunnyvale",
                      "postalAddress": {
                        "regionCode": "US",
                        "postalCode": "94086",
                        "administrativeArea": "CA",
                        "locality": "Sunnyvale",
                        "addressLines": [
                          "222, Some other Street"
                        ]
                      }
                    }
                  }
                }
              ]
            },
            "buyerInfo": {
              "email": "janedoe@gmail.com",
              "firstName": "Jane",
              "lastName": "Doe",
              "displayName": "Jane Doe"
            },
            "followUpActions": [
              {
                "type": "VIEW_DETAILS",
                "title": "View details",
                "openUrlAction": {
                  "url": "https://example.com"
                }
              },
              {
                "type": "CALL",
                "title": "Call us",
                "openUrlAction": {
                  "url": "tel:+16501112222"
                }
              },
              {
                "type": "EMAIL",
                "title": "Email us",
                "openUrlAction": {
                  "url": "mailto:person@example.com"
                }
              }
            ],
            "termsOfServiceUrl": "https://www.example.com"
          }
        }
      }
    }
  }
}
قالب JSON کیت توسعه نرم‌افزار Actions

توجه داشته باشید که JSON زیر پاسخ وب‌قلاب را شرح می‌دهد.

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TRANSACTION_DECISION",
          "inputValueData": {
            "@type": "type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec",
            "orderOptions": {
              "requestDeliveryAddress": "false"
            },
            "presentationOptions": {
              "actionDisplayName": "RESERVE"
            },
            "order": {
              "createTime": "2019-07-17T18:25:30.057Z",
              "lastUpdateTime": "2019-07-17T18:25:30.057Z",
              "merchantOrderId": "UNIQUE_ORDER_ID",
              "userVisibleOrderId": "USER_VISIBLE_ORDER_ID",
              "transactionMerchant": {
                "id": "https://www.example.com",
                "name": "Example Merchant"
              },
              "contents": {
                "lineItems": [
                  {
                    "id": "LINE_ITEM_ID",
                    "name": "Dinner reservation",
                    "description": "A world of flavors all in one destination.",
                    "reservation": {
                      "status": "PENDING",
                      "userVisibleStatusLabel": "Reservation is pending.",
                      "type": "RESTAURANT",
                      "reservationTime": {
                        "timeIso8601": "2020-01-16T01:30:15.01Z"
                      },
                      "userAcceptableTimeRange": {
                        "timeIso8601": "2020-01-15/2020-01-17"
                      },
                      "partySize": 6,
                      "staffFacilitators": [
                        {
                          "name": "John Smith"
                        }
                      ],
                      "location": {
                        "zipCode": "94086",
                        "city": "Sunnyvale",
                        "postalAddress": {
                          "regionCode": "US",
                          "postalCode": "94086",
                          "administrativeArea": "CA",
                          "locality": "Sunnyvale",
                          "addressLines": [
                            "222, Some other Street"
                          ]
                        }
                      }
                    }
                  }
                ]
              },
              "buyerInfo": {
                "email": "janedoe@gmail.com",
                "firstName": "Jane",
                "lastName": "Doe",
                "displayName": "Jane Doe"
              },
              "followUpActions": [
                {
                  "type": "VIEW_DETAILS",
                  "title": "View details",
                  "openUrlAction": {
                    "url": "https://example.com"
                  }
                },
                {
                  "type": "CALL",
                  "title": "Call us",
                  "openUrlAction": {
                    "url": "tel:+16501112222"
                  }
                },
                {
                  "type": "EMAIL",
                  "title": "Email us",
                  "openUrlAction": {
                    "url": "mailto:person@example.com"
                  }
                }
              ],
              "termsOfServiceUrl": "https://www.example.com"
            }
          }
        }
      ]
    }
  ]
}
مدیریت تصمیم کاربر

پس‌از اینکه کاربر به سفارش پیشنهادی پاسخ داد، اجرای شما قصد actions_intent_TRANSACTION_DECISION را با استدلالی حاوی TransactionDecisionValue دریافت می‌کند. این مقدار شامل موارد زیر خواهد بود:

  • transactionDecision - تصمیم کاربر درباره سفارش پیشنهادی. مقادیر ممکن عبارتند از ORDER_ACCEPTED، ORDER_REJECTED، CART_CHANGE_REQUESTED، و USER_CANNOT_TRANSACT.

برای رسیدگی به این درخواست، هدف Dialogflow را که با رویداد actions_intent_TRANSACTION_DECISION راه‌اندازی می‌شود اعلام کنید. این قصد را در اجرایتان مدیریت کنید:

Node.js
const arg = conv.arguments.get('TRANSACTION_DECISION_VALUE');
if (arg && arg.transactionDecision === 'ORDER_ACCEPTED') {
  console.log('order accepted');
  const order = arg.order;
}
جاوا
Argument transactionDecisionValue = request
    .getArgument("TRANSACTION_DECISION_VALUE");
Map<String, Object> extension = null;
if (transactionDecisionValue != null) {
  extension = transactionDecisionValue.getExtension();
}

String transactionDecision = null;
if (extension != null) {
  transactionDecision = (String) extension.get("transactionDecision");
}
if ((transactionDecision != null && transactionDecision.equals("ORDER_ACCEPTED"))) {
  OrderV3 order = ((OrderV3) extension.get("order"));
}
Dialogflow JSON

توجه داشته باشید که JSON زیر درخواست وب‌قلاب را شرح می‌دهد.

{
  "responseId": "",
  "queryResult": {
    "queryText": "",
    "action": "",
    "parameters": {},
    "allRequiredParamsPresent": true,
    "fulfillmentText": "",
    "fulfillmentMessages": [],
    "outputContexts": [],
    "intent": {
      "name": "reservation_get_transaction_decision_df",
      "displayName": "reservation_get_transaction_decision_df"
    },
    "intentDetectionConfidence": 1,
    "diagnosticInfo": {},
    "languageCode": ""
  },
  "originalDetectIntentRequest": {
    "source": "google",
    "version": "2",
    "payload": {
      "isInSandbox": true,
      "surface": {
        "capabilities": [
          {
            "name": "actions.capability.SCREEN_OUTPUT"
          },
          {
            "name": "actions.capability.AUDIO_OUTPUT"
          },
          {
            "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
          },
          {
            "name": "actions.capability.WEB_BROWSER"
          }
        ]
      },
      "inputs": [
        {
          "rawInputs": [],
          "intent": "",
          "arguments": []
        }
      ],
      "user": {},
      "conversation": {},
      "availableSurfaces": [
        {
          "capabilities": [
            {
              "name": "actions.capability.SCREEN_OUTPUT"
            },
            {
              "name": "actions.capability.AUDIO_OUTPUT"
            },
            {
              "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
            },
            {
              "name": "actions.capability.WEB_BROWSER"
            }
          ]
        }
      ]
    }
  },
  "session": ""
}
قالب JSON کیت توسعه نرم‌افزار Actions

توجه داشته باشید که JSON زیر درخواست وب‌قلاب را شرح می‌دهد.

{
  "user": {},
  "device": {},
  "surface": {
    "capabilities": [
      {
        "name": "actions.capability.SCREEN_OUTPUT"
      },
      {
        "name": "actions.capability.AUDIO_OUTPUT"
      },
      {
        "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
      },
      {
        "name": "actions.capability.WEB_BROWSER"
      }
    ]
  },
  "conversation": {},
  "inputs": [
    {
      "rawInputs": [],
      "intent": "reservation_get_transaction_decision_asdk",
      "arguments": []
    }
  ],
  "availableSurfaces": [
    {
      "capabilities": [
        {
          "name": "actions.capability.SCREEN_OUTPUT"
        },
        {
          "name": "actions.capability.AUDIO_OUTPUT"
        },
        {
          "name": "actions.capability.MEDIA_RESPONSE_AUDIO"
        },
        {
          "name": "actions.capability.WEB_BROWSER"
        }
      ]
    }
  ]
}

۴. رزرو را نهایی کنید و رسید ارسال کنید

وقتی هدف actions.intent.TRANSACTION_DECISION با transactionDecision ORDER_ACCEPTED برمی‌گردد، هر پردازشی را که برای زمان‌بندی رزرو لازم است (مثل ذخیره کردن آن در پایگاه داده خودتان) انجام دهید.

پاسخ ساده‌ای ارسال کنید تا مکالمه ادامه پیدا کند. کاربر «کارت رسید جمع‌شده‌ای» همراه با پاسخ شما دریافت می‌کند.

تحویل سفارشات

Node.js
// Set lastUpdateTime and update status of reservation
order.lastUpdateTime = new Date().toISOString();
order.reservation.status = 'CONFIRMED';
order.reservation.userVisibleStatusLabel = 'Reservation confirmed';
order.reservation.confirmationCode = '123ABCDEFGXYZ';

// Send synchronous order update
conv.ask(`Transaction completed! You're all set!`);
conv.ask(new OrderUpdate({
  type: 'SNAPSHOT',
  reason: 'Reason string',
  order: order,
}));
جاوا
ResponseBuilder responseBuilder = getResponseBuilder(request);
order.setLastUpdateTime(Instant.now().toString());

// Set reservation status to confirmed and provide confirmation code
LineItemV3 lineItem = order.getContents().getLineItems().get(0);
ReservationItemExtension reservationItemExtension = lineItem.getReservation();
reservationItemExtension.setStatus("CONFIRMED");
reservationItemExtension.setUserVisibleStatusLabel("Reservation confirmed.");
reservationItemExtension.setConfirmationCode("123ABCDEFGXYZ");
lineItem.setReservation(reservationItemExtension);
order.getContents().getLineItems().set(0, lineItem);

// Order update
OrderUpdateV3 orderUpdate = new OrderUpdateV3()
    .setType("SNAPSHOT")
    .setReason("Reason string")
    .setOrder(order);

responseBuilder
    .add("Transaction completed! You're all set! Would you like to do anything else?")
    .add(new StructuredResponse().setOrderUpdateV3(orderUpdate));
return responseBuilder.build();
Dialogflow JSON

توجه داشته باشید که JSON زیر پاسخ وب‌قلاب را شرح می‌دهد.

{
  "payload": {
    "google": {
      "expectUserResponse": true,
      "richResponse": {
        "items": [
          {
            "simpleResponse": {
              "textToSpeech": "Transaction completed! You're all set!"
            }
          },
          {
            "structuredResponse": {
              "orderUpdateV3": {
                "type": "SNAPSHOT",
                "reason": "Reason string",
                "order": {
                  "merchantOrderId": "UNIQUE_ORDER_ID",
                  "reservation": {
                    "status": "CONFIRMED",
                    "userVisibleStatusLabel": "Reservation confirmed",
                    "confirmationCode": "123ABCDEFGXYZ"
                  },
                  "lastUpdateTime": "2019-07-17T18:25:30.187Z"
                }
              }
            }
          }
        ]
      }
    }
  }
}
قالب JSON کیت توسعه نرم‌افزار Actions

توجه داشته باشید که JSON زیر پاسخ وب‌قلاب را شرح می‌دهد.

{
  "expectUserResponse": true,
  "expectedInputs": [
    {
      "possibleIntents": [
        {
          "intent": "actions.intent.TEXT"
        }
      ],
      "inputPrompt": {
        "richInitialPrompt": {
          "items": [
            {
              "simpleResponse": {
                "textToSpeech": "Transaction completed! You're all set!"
              }
            },
            {
              "structuredResponse": {
                "orderUpdateV3": {
                  "type": "SNAPSHOT",
                  "reason": "Reason string",
                  "order": {
                    "merchantOrderId": "UNIQUE_ORDER_ID",
                    "reservation": {
                      "status": "CONFIRMED",
                      "userVisibleStatusLabel": "Reservation confirmed",
                      "confirmationCode": "123ABCDEFGXYZ"
                    },
                    "lastUpdateTime": "2019-07-17T18:25:30.059Z"
                  }
                }
              }
            }
          ]
        }
      }
    }
  ]
}

۵. ارسال به‌روزرسانی‌های سفارش

وضعیت رزرو درطول عمر آن تغییر می‌کند. به‌روزرسانی‌های سفارش رزرو کاربر را با درخواست‌های HTTP PATCH به Orders API ارسال کنید، که شامل وضعیت و جزئیات سفارش است.

راه‌اندازی درخواست‌های ناهمگام به Orders API

درخواست‌های به‌روزرسانی سفارش به Orders API با کد دسترسی مجاز می‌شوند. برای PATCH کردن به‌روزرسانی سفارش در Orders API، کلید حساب سرویس JSON منسوب به پروژه «کنسول Actions» خود را بارگیری کنید، سپس کلید حساب سرویس را با رمزیاب دارنده که می‌تواند به سرصفحه Authorization درخواست HTTP منتقل شود مبادله کنید.

برای بازیابی کلید حساب سرویس، مراحل زیر را انجام دهید:

  1. در کنسول Google Cloud، به منو ☰ > میاناهای برنامه‌سازی کاربردی و سرویس‌ها > اطلاعات اعتباری > ایجاد اطلاعات اعتباری > کلید حساب سرویس بروید.
  2. در بخش حساب سرویس، حساب سرویس جدید را انتخاب کنید.
  3. حساب سرویس را روی service-account تنظیم کنید.
  4. نقش را روی پروژه > مالک تنظیم کنید.
  5. نوع کلید را روی JSON تنظیم کنید.
  6. ساختن را انتخاب کنید.
  7. کلید حساب سرویس JSON خصوصی در دستگاه محلی شما بارگیری خواهد شد.

در کد به‌روزرسانی‌های سفارش، کلید سرویس خود را بااستفاده از کتابخانه کارخواه Google APIs و دامنه "https://www.googleapis.com/auth/actions.order.developer" با یک رمزیاب دارنده مبادله کنید. می‌توانید مراحل نصب و نمونه‌ها را در صفحه GitHub کتابخانه کارخواه میانای برنامه‌سازی کاربردی پیدا کنید.

برای مشاهده نمونه تبادل کلید، به order-update.js در نمونه‌های Node.js و Java ما مراجعه کنید.

ارسال به‌روزرسانی‌های سفارش

وقتی کلید حساب سرویس را با یک رمزیاب دارنده OAuth مبادله کردید، به‌روزرسانی‌های سفارش را به‌عنوان درخواست‌های PATCH مجاز به Orders API ارسال کنید.

نشانی وب Orders API: PATCH https://actions.googleapis.com/v3/orders/${orderId}

سرصفحه‌های زیر را در درخواستتان ارائه دهید:

  • "Authorization: Bearer token" با رمزیاب دارنده OAuth که با کلید حساب سرویس خود مبادله کرده‌اید.
  • "Content-Type: application/json".

درخواست PATCH باید بدنه JSON با قالب زیر داشته باشد:

{ "orderUpdate": OrderUpdate }

شیء OrderUpdate شامل فیلدهای سطح بالای زیر است:

  • updateMask - فیلدهای سفارشی که درحال به‌روزرسانی آن هستید. برای به‌روزرسانی وضعیت رزرو، مقدار را روی reservation.status, reservation.userVisibleStatusLabel تنظیم کنید.
  • order - محتوای به‌روزرسانی. اگر درحال به‌روزرسانی محتوای رزرو هستید، مقدار را روی شیء Order به‌روزشده تنظیم کنید. اگر فقط وضعیت رزرو را به‌روز می‌کنید (برای مثال، از "PENDING" به "FULFILLED")، شیء حاوی فیلدهای زیر است:

    • merchantOrderId - همان شناسه‌ای که در شیء Order تنظیم کرده‌اید.
    • lastUpdateTime - مُهر زمان این به‌روزرسانی.
    • purchase - شیء حاوی موارد زیر:
      • status - وضعیت سفارش به‌عنوان ReservationStatus، مانند «CONFIRMED» یا «CANCELLED».
      • userVisibleStatusLabel - برچسبی که کاربر می‌بیند و جزئیاتی درباره وضعیت سفارش ارائه می‌دهد، مثلاً «رزرو شما تأیید شد».
  • userNotification (اختیاری) - شیء userNotification که می‌تواند هنگام ارسال این به‌روزرسانی در دستگاه کاربر نمایش داده شود. توجه داشته باشید که گنجاندن این شیء تضمین نمی‌کند که اعلانی در دستگاه کاربر ظاهر شود.

نمونه کد زیر مثالی از OrderUpdate را نشان می‌دهد که وضعیت سفارش رزرو را به FULFILLED به‌روز می‌کند:

Node.js
// Import the 'googleapis' module for authorizing the request.
const {google} = require('googleapis');
// Import the 'request' module for sending an HTTP POST request.
const request = require('request');
// Import the OrderUpdate class from the Actions on Google client library.
const {OrderUpdate} = require('actions-on-google');
// Import the service account key used to authorize the request. Replace the string path with a path to your service account key.
const key = require('./service-account.json');
// Create a new JWT client for the Actions API using credentials from the service account key.
let jwtClient = new google.auth.JWT(
    key.client_email,
    null,
    key.private_key,
    ['https://www.googleapis.com/auth/actions.order.developer'],
    null
);
// Authorize the client asynchronously, passing in a callback to run upon authorization.
jwtClient.authorize((err, tokens) => {
    if (err) {
        console.log(err);
        return;
    }
    // Declare the ID of the order to update.
    const orderId = '<UNIQUE_MERCHANT_ORDER_ID>';

    const orderUpdateJson = new OrderUpdate({
        updateMask: [
          'lastUpdateTime',
          'contents.lineItems.reservation.status',
          'contents.lineItems.reservation.userVisibleStatusLabel',
      ].join(','),
        order: {
          merchantOrderId: orderId,
          lastUpdateTime: new Date().toISOString(),
          contents: {
            lineItems: [
              {
                reservation: {
                  status: 'FULFILLED',
                  userVisibleStatusLabel: 'Reservation fulfilled',
                },
              }
            ]
          }
        },
        reason: 'Reservation status was updated to fulfilled.',
    });

    // Set up the PATCH request header and body, including the authorized token
    // and order update.
    const bearer = 'Bearer ' + tokens.access_token;
    const options = {
        method: 'PATCH',
        url: `https://actions.googleapis.com/v3/orders/${orderId}`,
        headers: {
          'Authorization': bearer,
        },
        body: {
          header: {
            'isInSandbox': true,
          },
          orderUpdate: orderUpdateJson,
        },
        json: true,
      };
    // Send the PATCH request to the Orders API.
    request.patch(options, (err, httpResponse, body) => {
        if (err) {
            console.log('There was an error...');
            console.log(err);
            return;
        }
    });
});
جاوا
// Create order update
FieldMask fieldMask = FieldMask.newBuilder().addAllPaths(Arrays.asList(
    "lastUpdateTime",
    "contents.lineItems.reservation.status",
    "contents.lineItems.reservation.userVisibleStatusLabel"))
    .build();

OrderUpdateV3 orderUpdate = new OrderUpdateV3()
    .setOrder(new OrderV3()
        .setMerchantOrderId(orderId)
        .setLastUpdateTime(Instant.now().toString())
        .setContents(new OrderContents()
        .setLineItems(Collections.singletonList(new LineItemV3()
            .setReservation(new ReservationItemExtension()
                .setStatus("FULFILLED")
                .setUserVisibleStatusLabel("Reservation fulfilled."))))))
    .setUpdateMask(FieldMaskUtil.toString(fieldMask))
    .setReason("Reservation status was updated to fulfilled.");

// Setup JSON body containing order update
JsonParser parser = new JsonParser();
JsonObject orderUpdateJson =
    parser.parse(new Gson().toJson(orderUpdate)).getAsJsonObject();
JsonObject body = new JsonObject();
body.add("orderUpdate", orderUpdateJson);
JsonObject header = new JsonObject();
header.addProperty("isInSandbox", true);
body.add("header", header);
StringEntity entity = new StringEntity(body.toString());
entity.setContentType(ContentType.APPLICATION_JSON.getMimeType());
request.setEntity(entity);

// Make request
HttpClient httpClient = HttpClientBuilder.create().build();
HttpResponse response = httpClient.execute(request);
تنظیم وضعیت رزرو

ReservationStatus به‌روزرسانی سفارش باید توصیف‌کننده وضعیت فعلی سفارش باشد. در فیلد order.ReservationStatus به‌روزرسانی‌تان، از یکی از مقادیر زیر استفاده کنید:

  • PENDING - رزرو توسط «اقدام» شما «ایجاد شده است» اما به پردازش بیشتری در پس‌بخش شما نیاز دارد.
  • CONFIRMED - رزرو در باطن زمان‌بندی شما تأیید شده است.
  • CANCELLED - کاربر رزرو خود را لغو کرد.
  • FULFILLED - رزرو کاربر توسط سرویس انجام شد.
  • CHANGE_REQUESTED - کاربر درخواست تغییر در رزرو را داده است و این تغییر درحال پردازش است.
  • REJECTED - اگر نتوانستید رزرو را پردازش یا به‌نحوی تأیید کنید.

برای هر وضعیتی که به رزرو شما مربوط است، به‌روزرسانی‌های سفارش را ارسال کنید. برای مثال، اگر رزرو شما برای تأیید رزرو پس‌از درخواست به پردازش دستی نیاز دارد، تا زمانی که پردازش اضافی انجام شود، به‌روزرسانی سفارش PENDING را ارسال کنید. همه رزروها به همه مقادیر وضعیت نیاز ندارند.

عیب‌یابی

اگر درطول آزمایش با مشکلی مواجه شدید، مراحل عیب‌یابی ما را برای تراکنش‌ها بخوانید.