เราจะยกเลิก Transaction API ในวันที่ 3 พฤษภาคม 2023 ก่อนที่จะเลิกใช้งานการดําเนินการเกี่ยวกับการสนทนาในวันที่ 13 มิถุนายน 2023 โปรดดูข้อมูลเพิ่มเติมที่หัวข้อการหยุดให้บริการการดําเนินการด้านการสนทนา

หน้านี้ได้รับการแปลโดย Cloud Translation API

สร้างการจอง

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

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

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

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

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

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

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

ออสเตรเลีย
บราซิล
แคนาดา
อินโดนีเซีย

ญี่ปุ่น
เม็กซิโก
กาตาร์
รัสเซีย

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

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

ดูตัวอย่างการสนทนาเกี่ยวกับธุรกรรมได้เพิ่มเติมในตัวอย่างธุรกรรมใน Node.js

ตั้งค่า

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

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

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

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

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

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

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

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

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

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

จากแท็บฉาก ให้เลือกฉาก TransactionRequirementsCheck ที่สร้างขึ้นใหม่
ในส่วนเงื่อนไข ให้คลิก + เพื่อเพิ่มเงื่อนไขใหม่
ในช่องข้อความ ให้ป้อนไวยากรณ์เงื่อนไขต่อไปนี้เพื่อตรวจสอบเงื่อนไขความสำเร็จ
```
scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"
```
วางเคอร์เซอร์เหนือเงื่อนไขที่เพิ่งเพิ่ม แล้วคลิกลูกศรขึ้นเพื่อวางไว้ก่อน if scene.slots.status == "FINAL"
เปิดใช้ส่งพรอมต์และใช้ข้อความแจ้งง่ายๆ เพื่อแจ้งให้ผู้ใช้ทราบว่าพร้อมทำธุรกรรมแล้ว ดังนี้
```
candidates:
  - first_simple:
      variants:
        - speech: >-
            Looks like you're good to go!.
```
ในส่วนการเปลี่ยน ให้เลือกฉากอื่น ซึ่งจะอนุญาตให้ผู้ใช้สนทนาต่อและทำธุรกรรมต่อ
เลือกเงื่อนไข else if scene.slots.status == "FINAL"
เปิดใช้ส่งพรอมต์และใช้ข้อความแจ้งง่ายๆ เพื่อแจ้งให้ผู้ใช้ทราบว่าตนทำธุรกรรมไม่ได้ ดังนี้
```
candidates:
  - first_simple:
      variants:
        - speech: Transaction requirements check failed.
```
ในส่วนการเปลี่ยน ให้เลือกสิ้นสุดการสนทนาเพื่อสิ้นสุดการสนทนา หากผู้ใช้ทำธุรกรรมไม่ได้

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

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

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

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

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

รวบรวมรายละเอียดการจองของผู้ใช้ตลอดการสนทนา แล้วสร้างออบเจ็กต์ 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'
    };

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

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

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

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

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

สร้างโหมดการตัดสินใจเกี่ยวกับธุรกรรม

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

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

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

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

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

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

ORDER_ACCEPTED,
ORDER_REJECTED,
CART_CHANGE_REQUESTED
USER_CANNOT_TRANSACT.

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

จากแท็บฉาก ให้เลือกฉาก TransactionDecision ที่สร้างขึ้นใหม่
ในส่วนเงื่อนไข ให้คลิก + เพื่อเพิ่มเงื่อนไขใหม่
ในช่องข้อความ ให้ป้อนไวยากรณ์เงื่อนไขต่อไปนี้เพื่อตรวจสอบเงื่อนไขความสำเร็จ
```
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
```
วางเคอร์เซอร์เหนือเงื่อนไขที่เพิ่งเพิ่ม แล้วคลิกลูกศรขึ้นเพื่อวางไว้หน้า if scene.slots.status == "FINAL"
เปิดใช้ส่งพรอมต์และใช้ข้อความแจ้งง่ายๆ เพื่อแจ้งให้ผู้ใช้ทราบว่าการจองเสร็จสมบูรณ์แล้ว
```
candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction completed! Your reservation
            $session.params.TransactionDecision.order.merchantOrderId is all
            set!
```
เลือกสิ้นสุดการสนทนาเพื่อสิ้นสุดการสนทนาในส่วนการเปลี่ยน
ในส่วนเงื่อนไข ให้คลิก + เพื่อเพิ่มเงื่อนไขใหม่
ในช่องข้อความ ให้ป้อนไวยากรณ์เงื่อนไขต่อไปนี้เพื่อตรวจสอบเงื่อนไขที่ล้มเหลว
```
  scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"
```
วางเคอร์เซอร์เหนือเงื่อนไขที่เพิ่งเพิ่ม แล้วคลิกลูกศรขึ้นเพื่อวางไว้หน้า if scene.slots.status == "FINAL"
เปิดใช้ส่งพรอมต์และใช้ข้อความแจ้งง่ายๆ เพื่อแจ้งให้ผู้ใช้ทราบว่าคำสั่งซื้อถูกปฏิเสธแล้วดังนี้
```
candidates:
  - first_simple:
      variants:
        - speech: Looks like you don't want to set up a reservation. Goodbye.
```
เลือกสิ้นสุดการสนทนาเพื่อสิ้นสุดการสนทนาในส่วนการเปลี่ยน
เลือกเงื่อนไข else if scene.slots.status == "FINAL"
เปิดใช้ส่งพรอมต์และใช้ข้อความแจ้งง่ายๆ เพื่อแจ้งให้ผู้ใช้ทราบว่าทำธุรกรรมไม่ได้
```
candidates:
  - first_simple:
      variants:
        - speech: >-
            Transaction failed with status
            $session.params.TransactionDecision.transactionDecision
```
ในส่วนการเปลี่ยน ให้เลือกสิ้นสุดการสนทนาเพื่อสิ้นสุดการสนทนา หากผู้ใช้ทำธุรกรรมไม่ได้

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

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

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

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

จากแท็บฉาก ให้เลือกฉาก TransactionDecision ของคุณ
ในส่วนเงื่อนไข ให้เลือกเงื่อนไขที่ตรวจสอบผลลัพธ์สำเร็จ ORDER_ACCEPTED:
```
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"
```
สําหรับเงื่อนไขนี้ ให้เปิดใช้โทรหาเว็บฮุค และระบุชื่อแฮนเดิล Intent เช่น update_order

ในโค้ดเว็บฮุค ให้เพิ่มเครื่องจัดการ 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 ได้

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

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

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

อ้างอิง 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 ที่แสดงในอุปกรณ์ของผู้ใช้ได้เมื่อส่งการอัปเดตนี้ โปรดทราบว่าการรวมออบเจ็กต์นี้ไม่ได้รับประกันว่าการแจ้งเตือนจะปรากฏในอุปกรณ์ของผู้ใช้

โค้ดตัวอย่างต่อไปนี้แสดงตัวอย่าง 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 ให้คลิกทดสอบในการนําทาง
คลิกการตั้งค่า
เปิดใช้ตัวเลือกแซนด์บ็อกซ์สำหรับการพัฒนา

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

การแก้ปัญหา

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