تعديل الطلب غير المتزامن

بعد أن يرسِل العميل طلب الطعام، يمكنك إرسال رسالة لتعديل الطلب إلى الخدمة الشاملة للطلب لإعلامنا بالتغيير.

في ما يلي بعض الأسباب الشائعة لإرسال تعديلات الطلبات:

• يصبح الوقت المقدَّر لتسليم الطلب متاحًا أو يتم تغييره.
• تتغير حالة الطلب.
• لم يعُد من الممكن تنفيذ الطلب.
• تم تغيير سعر صنف في قائمة الطعام مضمَّن في الطلب.
• لدى العميل طريقة جديدة لإدارة طلبه، مثل خدمة دعم العملاء. أو رقم هاتف المطعم.
• يصبح إيصال الطلب متاحًا.

تقدم الأقسام التالية تفاصيل حول كيفية التعامل مع هذه السيناريوهات المختلفة باستخدام تحديثات الطلبات.

حالات الطلبات الانتقالية

يحتوي الطلب على ست حالات محتملة. هذه الولايات وتحولاتها المحتملة في المخطط التالي:

عندما يرسل العميل طلبًا لأول مرة، يبدأ الطلب بحالة CREATED أو CONFIRMED أو REJECTED يمكنك إرسال رسالة تعديل الطلب إلى تعديل حالة الطلب، طالما أنّ عملية انتقال الولاية صالحة. CREATED يتم استخدام الحالة عندما يتعذّر على منصة الشريك تأكيد الطلب أو رفضه. فورًا. ومن الأمثلة على حالة الاستخدام عندما يطلب العميل المنتج من خلال عملية توصيل. موقع تجميع. يتلقى مجمّع التوصيل التسليم من Google، خدمة تجميع البيانات إلى المطعم. بمجرد استلام المطعم وأكّدت توفّر الطلب، ويمكن أن تكون الولاية الآن CONFIRMED، وبخلاف ذلك REJECTED

ينتقل الطلب في الحالة CONFIRMED بعد ذلك إلى الحالة IN_PREPARATION. استنادًا إلى ما إذا كان الطلب مخصّصًا للاستلام أو التسليم، يجب استخدام حالة READY_FOR_PICKUP أو IN_TRANSIT في المرة التالية. عندما يتم تسليم الطعام أو استلامه، يتم ضبط الطلب على حالة FULFILLED.

وإذا سمحت للعملاء بإلغاء الطلبات، يمكنك استخدام الولاية CANCELLED. يمكن إلغاء طلب أثناء التواجد في الحالة CREATED أو CONFIRMED أو IN_PREPARATION أو READY_FOR_PICKUP أو IN_TRANSIT. من المفترض أن تردّ الخدمة الشاملة للطلب عمليات ردّ الأموال استنادًا إلى سياسة الإلغاء وحالة الدفعات وقت الإلغاء.

لا يجب أن تدعم الخدمة الشاملة للطلب جميع الولايات المتاحة والانتقالات. ومع ذلك، يجب أن تكون الحالة النهائية للطلب FULFILLED، REJECTED أو CANCELLED.

توفير وقت تقديري لتوصيل الطلبات

يمكنك تزويد المستخدمين بنطاق زمني تقديري لموعد طلبهم. جاهزة للاستلام (أو التسليم). استخدام الحقل estimatedFulfillmentTimeIso8601 FoodOrderUpdateExtension لتوفير نطاق زمني تقديري للوقت الذي سيكون طلب العميل جاهزًا للاستلام أو التسليم.

أرسِل estimatedFulfillmentTimeIso8601 في الأوقات التالية:

• عندما يصبح الوقت المقدّر متاحًا، يُفضَّل أن يكون للطلب CREATED أو ولاية CONFIRMED.
• عند تغيير الوقت المقدر، مثل تحديث الوقت المقدر الذي سيتم أكثر دقة عندما يكون الطلب IN_TRANSIT.

لإدارة توقعات المستخدم بفعالية، كن متحفظًا في تقديراتك وفِّر نطاقًا للتاريخ والوقت بدلاً من تقديم تاريخ ووقت ثابتَين عليك عليك مراعاة الاختلافات، مثل أحوال عدد الزيارات، متى كان ذلك ممكنًا. بالنسبة على سبيل المثال، يمكنك إرسال تقدير بمدة 12:45 مساءً (بحد أدنى) إلى 1:15 مساءً (الحد الأعلى). تمامًا) للطلب الذي يكون وقت التسليم المقدّر فيه هو الساعة 1:00 بعد الظهر.

تقديم إجراءات إدارة الطلبات

عند إرسال تعديل لطلب معيّن، يمكنك توفير المراجع للعملاء الذين يساعدونك في ذلك. يدير طلبه في شكل OrderManagementAction. بعد يقدّم العميل طلبًا، قد يحتاج إلى التواصل معك أو مع المطعم الوفاء بالطلب لتتبع التقدم أو إجراء تغييرات أو إلغاء الطلب.

تتيح OrderManagementAction للعملاء إرسال رسائل إلكترونية أو إجراء مكالمات أو إضافة رابط إلى عنوان URL من جهاز المستخدم مباشرةً استخدم المعلومات نفسها في OrderManagementAction كما في رسالة تأكيد الطلب التي ترسلها إلى المستخدم.

تشمل إجراءات إدارة الطلبات الأنواع التالية:

• CUSTOMER_SERVICE: تزويد العملاء بإجراء للتواصل مع العميل خدمة ما. إنّ نوع إجراء الإدارة هذا مطلوب لتعديلات الطلبات.
• EMAIL: تزويد العملاء بإجراء لإرسال رسالة إلكترونية إلى العنوان المقدَّم بريدك الإلكتروني.
• CALL: تزويد العملاء بإجراء للاتصال برقم الهاتف المقدَّم.
• VIEW_DETAIL: تزويد العملاء بإجراء للاطّلاع على تفاصيل طلبك.

يجب أن يحتوي كل تحديث طلب على إجراء واحد على الأقل لإدارة الطلبات. ومع ذلك، قد تختلف إجراءات إدارة الطلبات المقدَّمة بناءً على حالة الطلب. على سبيل المثال، عندما يكون الطلب في حالة "CONFIRMED"، سيتم ضبط السمة CUSTOMER_SERVICE الإجراء إلى رقم هاتف خدمة العملاء. عندما ينص هذا الطلب التحديثات على IN_TRANSIT، يمكن أن يشير الإجراء CUSTOMER_SERVICE إلى رقم هاتف مطعم توصيل الطلبات.

إرسال تحديثات الطلب

يتم استخدام نوع الرسالة AsyncOrderUpdateRequestMessage لإرسال طلب. تحديث الخدمة الشاملة للطلب. تردّ Google باستخدام AsyncOrderUpdateResponseMessage على سبيل المثال، إذا أردت إبلاغ إلى العميل أن طلبه كان صالحًا ومقبولاً، يمكنك إرسال AsyncOrderUpdateRequestMessage لتغيير حالة الطلب إلى CONFIRMED تحمل التسمية Accepted by restaurant.

إعداد رسالة تعديل الطلب

عند إرسال "AsyncOrderUpdateRequestMessage" إلى Google، يجب تضمين معلومات عن حالة الطلب باستخدام الحقل OrderUpdate.

ملاحظة: actionOrderId هو المعرّف الفريد لتحديد الطلب الذي يجب تعديله. يجب أن تكون قيمة actionOrderId هي القيمة نفسها التي أرسلتها في عملية الإرسال. إجراء الطلب. إذا تم إنشاء الطلب مع ضبط isInSandbox على "صحيح"، يجب عليك عليك أيضًا تضمين قيمة isInSandbox التي تم ضبطها على "true" في isInSandbox.

تعرض الأمثلة التالية نموذج AsyncOrderUpdateRequestMessage من أجل حالة كل طلب:

تم تأكيد الحجز

يعرض هذا المثال نموذجًا لطلب تعديل الطلب الذي يُعلِم المستخدم. أنّه تم تأكيد الطلب مع إيصال استلام وتقدير التسليم الوقت.

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "CONFIRMED",
        "label": "Provider confirmed"
      },
      "receipt": {
        "userVisibleOrderId": "userVisibleId1234"
      },
      "updateTime": "2017-07-17T12:00:00Z",
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ],
      "infoExtension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "estimatedFulfillmentTimeIso8601": "2017-07-17T13:00:00Z/2017-07-17T13:30:00Z"
      }
    }
  }
}
    

مرفوضة

يعرض هذا المثال نموذجًا لطلب تعديل الطلب الذي يُعلِم المستخدم. أنه تم رفض الطلب لسبب الرفض.

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "REJECTED",
        "label": "Order rejected"
      },
      "updateTime": "2017-05-10T02:30:00.000Z",
      "rejectionInfo": {
        "type": "UNKNOWN",
        "reason": "Sorry, the restaurant cannot take your order right now."
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ],
      "infoExtension": {
      "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
      "foodOrderErrors": [
        {
        "error": "NO_CAPACITY",
        "description": "Sorry, the restaurant cannot take your order right now."
        }
      ]
      }
    }
  }
}
    

تم إلغاؤها

يعرض هذا المثال نموذجًا لطلب تعديل الطلب الذي يُعلِم المستخدم. أن الطلب تم إلغاؤه مع سبب الإلغاء.

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "CANCELLED",
        "label": "Order cancelled"
      },
      "updateTime": "2017-05-10T02:30:00.000Z",
      "cancellationInfo": {
        "reason": "Customer requested"
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ]
    }
  }
}
    

IN_PREPARATION

يعرض هذا المثال نموذجًا لطلب تعديل الطلب الذي يُعلِم المستخدم. أن الطعام يتم إعداده حاليًا.

{
  "isInSandbox":true,
  "customPushMessage":{
    "orderUpdate":{
      "actionOrderId":"sample_action_order_id",
      "orderState":{
        "state":"IN_PREPARATION",
        "label":"Order is being prepared"
      },
      "receipt": {
        "userVisibleOrderId": "userVisibleId1234"
      },
      "updateTime":"2018-04-15T11:30:00Z",
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ],
      "infoExtension":{
        "@type":"type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "estimatedFulfillmentTimeIso8601":"PT20M"
      }
    }
  }
}
    

READY_FOR_PICKUP

يعرض هذا المثال نموذجًا لطلب تعديل الطلب الذي يُعلِم المستخدم. أن الطعام جاهز للاستلام.

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "READY_FOR_PICKUP",
        "label": "Order is ready for pickup"
      },
      "receipt": {
        "userVisibleOrderId": "userVisibleId1234"
      },
      "updateTime": "2018-04-15T12:00:00Z",
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ],
      "infoExtension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "estimatedFulfillmentTimeIso8601": "PT20M"
      }
    }
  }
}
    

IN_TRANSIT

يعرض هذا المثال نموذجًا لطلب تعديل الطلب الذي يُعلِم المستخدم. أنّ الطلب في مرحلة النقل مع تقدير وقت التسليم

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
        "state": "IN_TRANSIT",
        "label": "Order is on the way"
      },
      "inTransitInfo": {
        "updatedTime": "2017-07-17T12:00:00Z"
      },
      "updateTime": "2017-07-17T12:00:00Z",
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ],
      "infoExtension": {
        "@type": "type.googleapis.com/google.actions.v2.orders.FoodOrderUpdateExtension",
        "estimatedFulfillmentTimeIso8601": "PT20M"
      }
    }
  }
}
  

تم استيفاء المتطلبات

يعرض هذا المثال نموذجًا لطلب تعديل الطلب الذي يُعلِم المستخدم. أن الطلب قد تم استلامه أو تسليمه:

{
  "isInSandbox": true,
  "customPushMessage": {
    "orderUpdate": {
      "actionOrderId": "sample_action_order_id",
      "orderState": {
      "state": "FULFILLED",
      "label": "Order delivered"
      },
      "updateTime": "2017-05-10T02:30:00.000Z",
      "fulfillmentInfo": {
        "deliveryTime": "2017-05-10T02:30:00.000Z"
      },
      "orderManagementActions": [
        {
          "type": "CUSTOMER_SERVICE",
          "button": {
            "title": "Contact customer service",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "EMAIL",
          "button": {
            "title": "Email restaurant",
            "openUrlAction": {
              "url": "mailto:[e-mail]"
            }
          }
        },
        {
          "type": "CALL_RESTAURANT",
          "button": {
            "title": "Call restaurant",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        },
        {
          "type": "CALL_DRIVER",
          "button": {
            "title": "Call driver",
            "openUrlAction": {
              "url": "tel:[phone]"
            }
          }
        }
      ]
    }
  }
}
    

للاطّلاع على المزيد من الأمثلة على طلبات تعديل الطلبات في حالات استخدام مختلفة، يُرجى الاطّلاع على: تنفيذ التعديلات المتقدّمة على الطلبات

إنشاء رمز مميّز للمصادقة وإرسال الرسالة

تتطلب تحديثات الطلب رمزًا مميزًا للتفويض بحيث يكون نظام إدارة الطلبات التحقق من أن الرسالة واردة من خدمة الويب الشاملة للطلب.

لتطبيق تعديلات الطلبات على مشروعك، اتّبِع الخطوات التالية:

1. يمكنك إنشاء رمز تفويض مميز باتّباع الخطوات التالية:
   1. استخدام مكتبة مصادقة Google لقراءة بيانات الاعتماد من خدمتك ملف الحساب.
   2. طلب رمز مميّز باستخدام النطاق التالي لواجهة برمجة التطبيقات: https://www.googleapis.com/auth/actions.fulfillment.conversation
2. استخدِم هذا الرمز المميّز لإرسال طلب HTTP POST تمت مصادقته إلى نقطة النهاية التالية: https://actions.googleapis.com/v2/conversations:send
3. يمكنك ضبط عنوان Content-Type على application/json كجزء من طلبك.

ملاحظة مُهمّة: عند إرسال تعديلات على الطلبات التي تم إجراؤها باستخدام ميزة "معاينة" البيئة، قم بتعيين الحقل isInSandbox من AsyncOrderUpdateRequestMessage إلى true.

توضّح الأمثلة التالية كيفية تطبيق التعديلات على الطلبات:

Node.js

يستخدم هذا الرمز مكتبة المصادقة من Google لنظام Node.js.

const {auth} = require('google-auth-library')
const request = require('request');
// The service account client secret file downloaded from the Google Cloud Console
const serviceAccountJson = require('./service-account.json')
// order-update.json is a file that contains the payload
const jsonBody = require('./order-update.json')

/**
 * Get the authorization token using a service account.
 */
async function getAuthToken() {
  let client = auth.fromJSON(serviceAccountJson)
  client.scopes = ['https://www.googleapis.com/auth/actions.fulfillment.conversation']
  const tokens = await client.authorize()
  return tokens.access_token;
}

/**
 * Send an order update request
 */
async function sendOrderUpdate() {
  const token = await getAuthToken()
  request.post({
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`
    },
    url: 'https://actions.googleapis.com/v2/conversations:send',
    body: jsonBody,
    json: true
  },
  (err, res, body) => {
    if (err) { return console.log(err); }
    console.log(`Response: ${JSON.stringify(res)}`)
  })
}
    

Python

يستخدم هذا الرمز مكتبة المصادقة من Google للغة Python.

from google.oauth2 import service_account
from google.auth.transport.requests import AuthorizedSession
import json

# service-account.json is the service account client secret file downloaded from the
# Google Cloud Console
credentials = service_account.Credentials.from_service_account_file(
    'service-account.json')

scoped_credentials = credentials.with_scopes(
    ['https://www.googleapis.com/auth/actions.fulfillment.conversation'])

authed_session = AuthorizedSession(scoped_credentials)

# order-update.json is a file that contains the payload
json_payload=json.load(open('order-update.json'))

response = authed_session.post(
    'https://actions.googleapis.com/v2/conversations:send',
    json=json_payload)
    

Java

يستخدم هذا الرمز مكتبة مصادقة Google للغة Java.

/**
 * Get the authorization token using a service account.
 */
private static String getAuthToken() {
  InputStream serviceAccountFile = Example.class.getClassLoader().getResourceAsStream("service-account.json");
  ServiceAccountCredentials.Builder credentialsSimpleBuilder =
      ServiceAccountCredentials.fromStream(serviceAccountFile).toBuilder();
  credentialsSimpleBuilder.setScopes(ImmutableList.of("https://www.googleapis.com/auth/actions.fulfillment.conversation"));
  AccessToken accessToken = credentialsSimpleBuilder.build().refreshAccessToken();
  return accessToken.getTokenValue();
}

/**
 * Send an order update request
 */
public void sendOrderUpdate() {
  String authToken = getAuthToken();
  // Execute POST request
  executePostRequest("https://actions.googleapis.com/v2/conversations:send",
      authToken, "update_order_example.json",);
}
    

لإجراء تعديلات ناجحة على الطلبات بدون أخطاء، يعرض محرّك بحث Google استجابة HTTP 200 ذات حمولة فارغة. إذا كانت هناك مشكلة، مثل ظهور التحديث بشكل غير صحيح، يعرض Google خطأ.