สร้างการจอง

คู่มือนี้จะอธิบายถึงกระบวนการพัฒนาโปรเจ็กต์ Actions ที่ใช้ Orders API ในการจอง

ขั้นตอนการทำธุรกรรม

เมื่อโปรเจ็กต์ Actions จัดการการจอง ใช้ขั้นตอนต่อไปนี้

  1. ตรวจสอบข้อกำหนดของธุรกรรม (ไม่บังคับ) - ใช้ธุรกรรม ตั้งแต่เริ่มบทสนทนาเพื่อให้มั่นใจได้ว่า ผู้ใช้ทำธุรกรรมได้
  2. สร้างคำสั่งซื้อ - แนะนำผู้ใช้เกี่ยวกับ "การประกอบรถเข็น" เพื่อสร้างรายละเอียดการจอง
  3. เสนอคำสั่งซื้อ - เมื่อ "รถเข็น" เสร็จแล้ว ให้เสนอการจอง "คำสั่งซื้อ" ถึง เพื่อให้ผู้ใช้ยืนยันได้ว่าข้อมูลถูกต้อง หากการจองได้รับการยืนยัน คุณจะ ได้รับการตอบกลับพร้อมรายละเอียดการจอง
  4. สรุปคำสั่งซื้อและส่งใบเสร็จ - อัปเดตคำสั่งซื้อเมื่อยืนยันคำสั่งซื้อแล้ว ระบบการจองของคุณ และส่งใบเสร็จให้ผู้ใช้
  5. ส่งการอัปเดตคำสั่งซื้อ - ตลอดอายุของการจอง อัปเดตสถานะการจองของผู้ใช้โดยส่งคำขอ PATCH ไปยัง Orders API

ข้อจำกัดและหลักเกณฑ์การตรวจสอบ

โปรดทราบว่านโยบายเพิ่มเติมจะมีผลกับการดำเนินการที่ใช้ ธุรกรรมและ Orders API การตรวจสอบการดําเนินการของเราอาจใช้เวลาสูงสุด 6 สัปดาห์ การทำธุรกรรมต่างๆ ดังนั้นอย่าลืมคำนึงถึงช่วงเวลาในการวางแผนกำหนดการเผยแพร่ของคุณ เพื่อช่วยให้กระบวนการตรวจสอบง่ายขึ้น โปรดตรวจสอบว่าคุณได้ปฏิบัติตาม นโยบายและหลักเกณฑ์สำหรับธุรกรรม ก่อนส่งการดำเนินการของคุณเข้ารับการตรวจสอบ

คุณจะติดตั้งใช้งานการดำเนินการที่ใช้ Orders API ได้ในประเทศต่อไปนี้เท่านั้น

ออสเตรเลีย
บราซิล
แคนาดา
อินโดนีเซีย 		ญี่ปุ่น
เม็กซิโก
กาตาร์
รัสเซีย 		สิงคโปร์
สวิตเซอร์แลนด์
ไทย
ตุรกี
สหราชอาณาจักร
สหรัฐอเมริกา

สร้างโปรเจ็กต์

สำหรับตัวอย่างเพิ่มเติมของการสนทนาเกี่ยวกับธุรกรรม โปรดดูที่ ธุรกรรม ของเรา ตัวอย่างใน Node.js

ตั้งค่า

เมื่อสร้างการดำเนินการ คุณต้องระบุว่าคุณต้องการทำธุรกรรม ในคอนโซล Actions

ในการตั้งค่าโปรเจ็กต์และการดำเนินการเพื่อดำเนินการตามคำสั่งซื้อ ให้ทำตามขั้นตอนต่อไปนี้

  1. สร้างโปรเจ็กต์ใหม่หรือนำเข้าโปรเจ็กต์ที่มีอยู่
  2. ไปที่ทำให้ใช้งานได้ > ข้อมูลไดเรกทอรี

  3. ใน ข้อมูลเพิ่มเติม > ธุรกรรม > เลือกช่องที่เขียนว่า "การดำเนินการของคุณ ใช้ Transaction API เพื่อทำธุรกรรมสินค้าที่จับต้องได้หรือไม่"

ตรวจสอบข้อกำหนดของธุรกรรม (ไม่บังคับ)

ทันทีที่ผู้ใช้ระบุว่าต้องการตั้งค่าการจอง คุณควรตรวจสอบ ว่าจะสามารถขอทำการจองได้ ตัวอย่างเช่น เมื่อเรียกใช้ การดำเนินการของคุณอาจ ถามว่า "คุณต้องการจองที่นั่งไหม" หากผู้ใช้ตอบว่า "ใช่" คุณควร เพื่อดำเนินการต่อและเปิดโอกาสให้แก้ไขการตั้งค่า และป้องกันไม่ให้ทำธุรกรรมต่อ โดยดำเนินการดังนี้ การเปลี่ยนฉากไปยังฉากที่ ตรวจสอบข้อกำหนดในการทำธุรกรรม

สร้างฉากการตรวจสอบข้อกำหนดสำหรับธุรกรรม

  1. จากแท็บฉาก ให้เพิ่มฉากใหม่ด้วยชื่อ TransactionRequirementsCheck
  2. ภายใต้การเติมช่อง ให้คลิก + เพื่อเพิ่มช่องใหม่
  3. ในส่วนเลือกประเภท ให้เลือก actions.type.TransactionRequirementsCheckResult เป็นประเภทช่องโฆษณา
  4. ในช่องชื่อช่อง ให้ตั้งชื่อช่องเป็น TransactionRequirementsCheck
  5. เปิดใช้ช่องทำเครื่องหมายปรับแต่งการเขียนกลับค่าช่องโฆษณา (เปิดใช้โดยค่าเริ่มต้น)

  6. คลิกบันทึก

การตรวจสอบข้อกำหนดด้านธุรกรรมจะให้ผลลัพธ์อย่างใดอย่างหนึ่งต่อไปนี้

  • หากตรงตามข้อกำหนด ระบบจะตั้งค่าพารามิเตอร์เซสชันให้ประสบความสำเร็จ คุณจึงสร้างคำสั่งซื้อของผู้ใช้ต่อได้
  • หากไม่สามารถปฏิบัติตามข้อกำหนดอย่างน้อย 1 ข้อ พารามิเตอร์เซสชันจะเป็น ด้วยเงื่อนไขความล้มเหลว ในกรณีนี้ คุณควรเปลี่ยนแนวทางการสนทนา ออกจากประสบการณ์การทำธุรกรรม หรือจบการสนทนาได้
    • หากผู้ใช้สามารถแก้ไขข้อผิดพลาดใดๆ ซึ่งส่งผลให้มีสถานะล้มเหลวได้ พวกเขาจะได้รับข้อความแจ้งให้แก้ไขปัญหาเหล่านั้นในอุปกรณ์ของตน หาก การสนทนาจะดำเนินบนพื้นผิวที่มีเฉพาะเสียง การส่งต่อจะ ไปยังโทรศัพท์ของผู้ใช้

จัดการผลการตรวจสอบข้อกำหนดด้านธุรกรรม

  1. จากแท็บฉาก ให้เลือกที่สร้างขึ้นใหม่ TransactionRequirementsCheck ฉาก
  2. ภายใต้เงื่อนไข ให้คลิก + เพื่อเพิ่มเงื่อนไขใหม่

  3. ในช่องข้อความ ให้ป้อนไวยากรณ์เงื่อนไขต่อไปนี้เพื่อตรวจสอบ เงื่อนไขความสำเร็จ:

    scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"

  4. วางเคอร์เซอร์เหนือเงื่อนไขที่คุณเพิ่งเพิ่ม แล้วคลิกลูกศรขึ้น เพื่อวางไว้ก่อนวันที่ if scene.slots.status == "FINAL"

  5. เปิดใช้ส่งข้อความแจ้งและแสดงข้อความแจ้งง่ายๆ เพื่อแจ้งให้ผู้ใช้ทราบ พวกเขาพร้อมที่จะทำธุรกรรม:

    candidates:
  - first_simple:
      variants:
        - speech: >-
            Looks like you're good to go!.

  6. ในส่วนการเปลี่ยน ให้เลือกฉากอื่นเพื่อให้ผู้ใช้ดำเนินการต่อ การสนทนาและทำธุรกรรมต่อ

  7. เลือกเงื่อนไข else if scene.slots.status == "FINAL"

  8. เปิดใช้ส่งข้อความแจ้งและแสดงข้อความแจ้งง่ายๆ เพื่อแจ้งให้ผู้ใช้ทราบ ทำธุรกรรมไม่ได้

    candidates:
  - first_simple:
      variants:
        - speech: Transaction requirements check failed.

  9. เลือกสิ้นสุดการสนทนาในส่วนการเปลี่ยนเพื่อสิ้นสุดการสนทนา หากผู้ใช้ทำธุรกรรมไม่ได้

สร้างคำสั่งซื้อ

เมื่อคุณมีข้อมูลผู้ใช้ที่ต้องการแล้ว ให้สร้าง "รถเข็น" การประกอบ" ที่เป็นแนวทางให้ผู้ใช้สร้างการจอง ทุก การดำเนินการจะมีขั้นตอนการประกอบรถเข็นที่แตกต่างกันเล็กน้อยตามความเหมาะสม service.

ในการประกอบรถเข็นแบบพื้นฐาน ผู้ใช้เลือกตัวเลือกจากรายการเพื่อเพิ่ม กับการจองของพวกเขา แต่คุณสามารถออกแบบบทสนทนาเพื่อให้ ประสบการณ์ของผู้ใช้ ตัวอย่างเช่น สร้างประสบการณ์การประกอบรถเข็นที่เปิดใช้ ผู้ใช้สามารถกำหนดเวลาจองรายเดือนด้วยคำถามง่ายๆ ว่าใช่หรือไม่ใช่ คุณยังแสดงการ์ดภาพสไลด์หรือการ์ดรายการที่ "แนะนำ" ให้แก่ผู้ใช้ได้ด้วย การจองล่วงหน้า

เราขอแนะนำให้ใช้การตอบกลับที่สมบูรณ์เพื่อ นำเสนอตัวเลือกของผู้ใช้ด้วยภาพ แต่ก็ยังออกแบบการสนทนาให้ ผู้ใช้สามารถสร้างรถเข็นโดยใช้เพียงเสียงเท่านั้น สำหรับแนวทางปฏิบัติแนะนำและ ดูตัวอย่างประสบการณ์การประกอบรถเข็นได้ที่หลักเกณฑ์การออกแบบ

สร้างคำสั่งซื้อ

รวบรวมรายละเอียดการจองของผู้ใช้ตลอดการสนทนา แล้ว สร้างออบเจ็กต์ Order

อย่างน้อย Order ต้องมีข้อมูลต่อไปนี้

  • buyerInfo - ข้อมูลเกี่ยวกับผู้ใช้ที่กำลังซื้อ
  • transactionMerchant - ข้อมูลเกี่ยวกับผู้ขายที่อำนวยความสะดวกด้านการสั่งซื้อ
  • contents - เนื้อหาจริงของคำสั่งซื้อที่แสดงเป็น lineItems

โปรดดูOrder เอกสารการตอบกลับสำหรับการสร้างรถเข็นของคุณ โปรดทราบว่าคุณอาจต้องใส่ ช่องที่ต่างกันขึ้นอยู่กับการจอง

โค้ดตัวอย่างด้านล่างแสดงคำสั่งซื้อการจองที่ครบถ้วน รวมถึงช่องที่ไม่บังคับ

const order = {
   createTime: '2019-09-24T18:00:00.877Z',
   lastUpdateTime: '2019-09-24T18:00:00.877Z',
   merchantOrderId: orderId, // A unique ID String for the order
   userVisibleOrderId: orderId,
   transactionMerchant: {
     id: 'http://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: 'http://example.com',
       },
     },
     {
       type: 'CALL',
       title: 'Call us',
       openUrlAction: {
         url: 'tel:+16501112222',
       },
     },
     {
       type: 'EMAIL',
       title: 'Email us',
       openUrlAction: {
         url: 'mailto:person@example.com',
       },
     },
   ],
   termsOfServiceUrl: 'http://www.example.com'
 };

สร้างตัวเลือกลำดับและการนำเสนอ

const orderOptions = {
      'requestDeliveryAddress': false,
    };

const presentationOptions = {
      'actionDisplayName': 'RESERVE'
    };

บันทึกข้อมูลคำสั่งซื้อในพารามิเตอร์เซสชัน

บันทึกข้อมูลคำสั่งซื้อลงในพารามิเตอร์เซสชันจากการดำเนินการตามคำสั่งซื้อ คำสั่งซื้อ จะใช้ข้ามฉากสำหรับเซสชันเดียวกัน

conv.session.params.order = {
    '@type': 'type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec',
    order: order,
    orderOptions: orderOptions,
    presentationOptions: presentationOptions
};

เสนอคำสั่งซื้อ

เมื่อคุณสร้างคำสั่งซื้อการจองแล้ว คุณต้องแสดงคำสั่งซื้อนั้นต่อผู้ใช้เพื่อ ยืนยันหรือปฏิเสธ จึงจะเปลี่ยนไปยังโหมดที่ทำธุรกรรมได้ การพิพากษาดังกล่าว

สร้างรูปแบบการตัดสินใจธุรกรรม

  1. จากแท็บฉาก ให้เพิ่มฉากใหม่ในชื่อ TransactionDecision
  2. ภายใต้การเติมช่อง ให้คลิก + เพื่อเพิ่มช่องใหม่
  3. ในส่วนเลือกประเภท ให้เลือก actions.type.TransactionDecisionValue เป็น ประเภทช่องโฆษณา
  4. ในช่องชื่อช่อง ให้ตั้งชื่อช่องเป็น TransactionDecision
  5. เปิดใช้ช่องทำเครื่องหมายปรับแต่งการเขียนกลับค่าช่องโฆษณา (เปิดใช้โดยค่าเริ่มต้น)
  6. ในส่วนกำหนดค่าสล็อต ให้เลือกใช้พารามิเตอร์เซสชันจากเมนูแบบเลื่อนลง
  7. ในส่วนกำหนดค่าช่องโฆษณา ให้ป้อนชื่อพารามิเตอร์เซสชันที่ใช้เพื่อ จัดเก็บคำสั่งซื้อลงในช่องข้อความ (เช่น $session.params.order)

  8. คลิกบันทึก

Assistant จะเริ่มต้นเพื่อเติมช่อง TransactionDecisionValue ประสบการณ์ในตัวซึ่ง Order ที่คุณส่งจะแสดงผลโดยตรงไปยัง "การ์ดแสดงตัวอย่างรถเข็น" ผู้ใช้อาจพูดว่า "กำหนดเวลาจอง" ปฏิเสธธุรกรรม หรือขอเปลี่ยนแปลงรายละเอียดการจอง

ในตอนนี้ ผู้ใช้ยังขอเปลี่ยนแปลงคำสั่งซื้อได้ด้วย ในกรณีนี้ คุณ ตรวจสอบว่าการดำเนินการตามคำสั่งซื้อรองรับคำขอเปลี่ยนแปลงคำสั่งซื้อได้หลังจาก การประกอบรถเข็นให้เสร็จ

จัดการผลการตัดสินใจในธุรกรรม

เมื่อช่องโฆษณา TransactionDecisionValue เต็ม คำตอบของผู้ใช้สำหรับ ระบบจะจัดเก็บการตัดสินใจเกี่ยวกับธุรกรรมไว้ในพารามิเตอร์เซสชัน ค่านี้ประกอบด้วย ดังต่อไปนี้

  • ORDER_ACCEPTED
  • ORDER_REJECTED
  • CART_CHANGE_REQUESTED
  • USER_CANNOT_TRANSACT

วิธีจัดการผลการตัดสินใจเกี่ยวกับธุรกรรม

  1. จากแท็บฉาก ให้เลือกฉาก TransactionDecision ที่สร้างขึ้นใหม่
  2. ภายใต้เงื่อนไข ให้คลิก + เพื่อเพิ่มเงื่อนไขใหม่

  3. ในช่องข้อความ ให้ป้อนไวยากรณ์เงื่อนไขต่อไปนี้เพื่อตรวจสอบ เงื่อนไขความสำเร็จ:

    scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"

  4. วางเคอร์เซอร์เหนือเงื่อนไขที่คุณเพิ่งเพิ่ม แล้วคลิกลูกศรขึ้น เพื่อวางไว้ก่อนวันที่ if scene.slots.status == "FINAL"

  5. เปิดใช้ส่งข้อความแจ้งและแสดงข้อความแจ้งง่ายๆ เพื่อแจ้งให้ผู้ใช้ทราบ การจองเสร็จสมบูรณ์

    candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction completed! Your reservation
            $session.params.TransactionDecision.order.merchantOrderId is all
            set!

  6. ในส่วนการเปลี่ยน ให้เลือกสิ้นสุดการสนทนาเพื่อสิ้นสุดการสนทนา

  7. ภายใต้เงื่อนไข ให้คลิก + เพื่อเพิ่มเงื่อนไขใหม่

  8. ในช่องข้อความ ให้ป้อนไวยากรณ์เงื่อนไขต่อไปนี้เพื่อตรวจสอบ เงื่อนไขความล้มเหลว:

      scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"

  9. วางเคอร์เซอร์เหนือเงื่อนไขที่คุณเพิ่งเพิ่ม แล้วคลิกลูกศรขึ้น เพื่อวางไว้ก่อนวันที่ if scene.slots.status == "FINAL"

  10. เปิดใช้ส่งข้อความแจ้งและแสดงข้อความแจ้งง่ายๆ เพื่อแจ้งให้ผู้ใช้ทราบว่า คำสั่งซื้อถูกปฏิเสธ:

    candidates:
  - first_simple:
      variants:
        - speech: Looks like you don't want to set up a reservation. Goodbye.

  11. ในส่วนการเปลี่ยน ให้เลือกสิ้นสุดการสนทนาเพื่อสิ้นสุดการสนทนา

  12. เลือกเงื่อนไข else if scene.slots.status == "FINAL"

  13. เปิดใช้ส่งข้อความแจ้งและแสดงข้อความแจ้งง่ายๆ เพื่อแจ้งให้ผู้ใช้ทราบ ทำธุรกรรมไม่ได้

    candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction failed with status
            $session.params.TransactionDecision.transactionDecision

  14. เลือกสิ้นสุดการสนทนาในส่วนการเปลี่ยนเพื่อสิ้นสุดการสนทนา หากผู้ใช้ทำธุรกรรมไม่ได้

ดำเนินการจองให้เสร็จสิ้นและส่งใบเสร็จ

เมื่อช่องโฆษณา TransactionDecisionValue แสดงผลลัพธ์เป็น ORDER_ACCEPTED คุณต้องดำเนินการตาม การประมวลผลที่จำเป็น ในทันทีเพื่อตั้งเวลา การจองไว้ (เช่น เก็บไว้ในฐานข้อมูลของคุณเอง)

ส่งคำตอบง่ายๆ เพื่อให้การสนทนาดำเนินไปอย่างต่อเนื่อง ผู้ใช้จะได้รับ "ยุบการ์ดใบเสร็จ" และคำตอบของคุณ

วิธีส่งการอัปเดตคำสั่งซื้อเริ่มต้น

  1. จากแท็บฉาก ให้เลือกฉาก TransactionDecision ของคุณ

  2. ในส่วนเงื่อนไข ให้เลือกเงื่อนไขที่จะตรวจสอบผลลัพธ์ที่สำเร็จ ORDER_ACCEPTED:

    scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"

  3. สำหรับเงื่อนไขนี้ ให้เปิดใช้เรียกใช้เว็บฮุค และระบุ Intent ชื่อเครื่องจัดการ เช่น update_order

  4. ในโค้ดเว็บฮุค ให้เพิ่มเครื่องจัดการ Intent เพื่อส่งการอัปเดตคำสั่งซื้อเริ่มต้น ดังนี้

    app.handle('update_order', conv => {
  const currentTime = new Date().toISOString();
  let order = conv.session.params.TransactionDecision.order;
  conv.add(new OrderUpdate({
    'updateMask': {
      'paths': [
        'reservation.status',
        'reservation.user_visible_status_label',
        'reservation.confirmation_code'
      ]
    },
    'order': {
      'merchantOrderId': order.merchantOrderId,
      'lastUpdateTime': currentTime,
      'reservation': {
        'status': 'CONFIRMED',
        'userVisibleStatusLabel': 'Reservation confirmed',
        'confirmationCode': '123ABCDEFGXYZ',
      },
    },
    'reason': 'Reason string'
  }));
});

ส่งการอัปเดตคำสั่งซื้อ

สถานะการจองจะเปลี่ยนแปลงตลอดอายุการใช้งาน ส่งผู้ใช้ การอัปเดตคำสั่งซื้อการจองด้วยคำขอ HTTP Patch ไปยัง Orders API โดยมี สถานะและรายละเอียดของคำสั่งซื้อ

ตั้งค่าคำขอแบบไม่พร้อมกันไปยัง Orders API

คำขออัปเดตคำสั่งซื้อไปยัง Orders API ได้รับอนุญาตแล้ว โทเค็น หากต้องการแพตช์การอัปเดตคำสั่งซื้อใน Orders API ให้ดาวน์โหลด JSON คีย์บัญชีบริการที่เชื่อมโยงกับโปรเจ็กต์คอนโซล Actions จากนั้นแลกเปลี่ยน คีย์บัญชีบริการสำหรับโทเค็นสำหรับผู้ถือที่ส่งไปยัง ส่วนหัว Authorization ของคำขอ HTTP

หากต้องการเรียกข้อมูลคีย์บัญชีบริการ ให้ทำตามขั้นตอนต่อไปนี้

  1. ในคอนโซล Google Cloud ไปที่ เมนู ☰ > API และ บริการ > ข้อมูลเข้าสู่ระบบ > สร้างข้อมูลเข้าสู่ระบบ > คีย์บัญชีบริการ
  2. ในส่วนบัญชีบริการ ให้เลือกบัญชีบริการใหม่
  3. ตั้งค่าบัญชีบริการเป็น service-account
  4. กำหนดบทบาทเป็นโปรเจ็กต์ > เจ้าของ
  5. ตั้งค่าประเภทคีย์เป็น JSON
  6. เลือกสร้าง
  7. ระบบจะดาวน์โหลดคีย์บัญชีบริการ JSON ส่วนตัวไปยังเครื่องภายในของคุณ

ในรหัสการอัปเดตคำสั่งซื้อ ให้แลกเปลี่ยนคีย์บริการเป็นโทเค็นสำหรับผู้ถือ โดยใช้ไลบรารีของไคลเอ็นต์ Google APIs และ "https://www.googleapis.com/auth/actions.order.developer" ขอบเขต คุณดู ขั้นตอนการติดตั้งและตัวอย่างในไลบรารีของไคลเอ็นต์ API หน้า GitHub

โปรดดู order-update.js ในตัวอย่าง Node.js ของเรา สำหรับการแลกเปลี่ยนคีย์

ส่งการอัปเดตคำสั่งซื้อ

เมื่อคุณแลกเปลี่ยนคีย์บัญชีบริการกับโทเค็นสำหรับผู้ถือ OAuth แล้ว ให้ส่ง อัปเดตคำสั่งซื้อเป็นคำขอ Patch ที่ได้รับอนุญาตไปยัง Orders API

URL ของ 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 (ไม่บังคับ) - A userNotification ที่สามารถแสดงในอุปกรณ์ของผู้ใช้เมื่อส่งการอัปเดตนี้ หมายเหตุ ว่าการใส่ออบเจ็กต์นี้ไม่ได้รับประกันว่าการแจ้งเตือนจะปรากฏใน อุปกรณ์ของผู้ใช้

โค้ดตัวอย่างต่อไปนี้แสดงตัวอย่าง OrderUpdate ที่อัปเดต สถานะของคำสั่งซื้อการจองไปยัง FULFILLED:

// Import the 'googleapis' module for authorizing the request.
const {google} = require('googleapis');
// Import the 'request-promise' module for sending an HTTP POST request.
const request = require('request-promise');
// Import the OrderUpdate class from the client library.
const {OrderUpdate} = require('@assistant/conversation');

// Import the service account key used to authorize the request.
// Replacing the string path with a path to your service account key.
// i.e. const serviceAccountKey = 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(
   serviceAccountKey.client_email,
   null,
   serviceAccountKey.private_key,
   ['https://www.googleapis.com/auth/actions.order.developer'],
   null,
);

// Authorize the client
let tokens = await jwtClient.authorize();

// Declare the ID of the order to update.
const orderId = '<UNIQUE_MERCHANT_ORDER_ID>';

// Declare order update
const orderUpdate = new OrderUpdate({
   updateMask: {
     paths: [
       'contents.lineItems.reservation.status',
       'contents.lineItems.reservation.userVisibleStatusLabel'
     ]
   },
   order: {
     merchantOrderId: orderId, // Specify the ID of the order to update
     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.
let options = {
 method: 'PATCH',
 uri: `https://actions.googleapis.com/v3/orders/${orderId}`,
 auth: {
   bearer: tokens.access_token,
 },
 body: {
   header: {
     isInSandbox: true,
   },
   orderUpdate,
 },
 json: true,
};

// Send the PATCH request to the Orders API.
try {
 await request(options);
} catch (e) {
 console.log(`Error: ${e}`);
}

ตั้งค่าสถานะการจอง

ReservationStatusของการอัปเดตคำสั่งซื้อ ต้องอธิบายถึงสถานะปัจจุบันของคำสั่งซื้อ ในorder.ReservationStatusของการอัปเดต ให้ใช้ค่าใดค่าหนึ่งต่อไปนี้

  • PENDING - การจองได้รับการ "สร้าง" แล้ว ตามการดำเนินการของคุณแต่ต้องใช้ การประมวลผลเพิ่มเติมในแบ็กเอนด์ของคุณ
  • CONFIRMED - การจองได้รับการยืนยันในระบบแบ็กเอนด์การกำหนดเวลาของคุณ
  • CANCELLED - ผู้ใช้ยกเลิกการจอง
  • FULFILLED - บริการได้ทำการจองของผู้ใช้แล้ว
  • CHANGE_REQUESTED - ผู้ใช้ขอให้เปลี่ยนแปลงการจอง โดยการเปลี่ยนแปลงเป็น กำลังประมวลผล
  • REJECTED - หากประมวลผลไม่ได้หรือดำเนินการไม่ได้ ยืนยันการจอง

ส่งการอัปเดตคำสั่งซื้อสำหรับแต่ละสถานะที่เกี่ยวข้องกับ การจองของคุณ เช่น หากการจองต้องใช้การประมวลผลด้วยตนเองเพื่อ ยืนยันการจองหลังจากที่ขอ ส่งอัปเดตคำสั่งซื้อของ PENDING จนถึง การประมวลผลเพิ่มเติมจะเสร็จสมบูรณ์ การจองบางรายการไม่ได้กำหนดให้ใช้ค่าสถานะบางรายการ

ทดสอบโปรเจ็กต์ของคุณ

เมื่อทดสอบโปรเจ็กต์ คุณจะเปิดใช้โหมดแซนด์บ็อกซ์ในคอนโซล Actions ได้ เพื่อทดสอบการดำเนินการของคุณโดยไม่เรียกเก็บเงินจากวิธีการชำระเงิน หากต้องการเปิดใช้งานโหมดแซนด์บ็อกซ์ ให้ทำตามขั้นตอนต่อไปนี้

  1. ในคอนโซล Actions ให้คลิกทดสอบในการนำทาง
  2. คลิกการตั้งค่า
  3. เปิดใช้ตัวเลือกแซนด์บ็อกซ์การพัฒนา

สำหรับธุรกรรมที่จับต้องได้ คุณยังตั้งค่าช่อง isInSandbox เป็น true ใน ตัวอย่างของคุณ การดําเนินการนี้เทียบเท่ากับการเปิดใช้การตั้งค่าโหมดแซนด์บ็อกซ์ใน คอนโซล Actions หากต้องการดูข้อมูลโค้ดที่ใช้ isInSandbox โปรดดูส่วน ส่วนส่งการอัปเดตคำสั่งซื้อ

การแก้ปัญหา

หากพบปัญหาระหว่างการทดสอบ โปรดอ่านขั้นตอนการแก้ปัญหา สำหรับธุรกรรม