แปลงแอป Google Chat แบบอินเทอร์แอกทีฟเป็นส่วนเสริม Google Workspace

หากคุณสร้างและเผยแพร่แอป Google Chat ที่ใช้เหตุการณ์การโต้ตอบของ Google Chat API เช่น เหตุการณ์ที่อิงตามการเริ่มต้นใช้งานแอป Google Chat อย่างรวดเร็ว หน้านี้จะแสดงวิธีแปลงแอปดังกล่าวเป็นส่วนเสริม Google Workspace ที่ขยาย Google Chat

การแปลงจะช่วยให้แอป Google Chat ใช้เฟรมเวิร์กส่วนเสริมของ Google Workspace ได้ ซึ่งจะเปิดโอกาสใหม่ๆ ในการผสานรวมและฟีเจอร์ต่างๆ ภายใน Google Chat และทั่วทั้ง Google Workspace ตัวอย่างเช่น คุณสามารถเผยแพร่ส่วนเสริม Google Workspace รายการเดียว ผ่าน Google Workspace Marketplace ซึ่งจะขยายแอป Chat ควบคู่ไปกับแอปพลิเคชันโฮสต์อื่นๆ ของ Google Workspace เช่น Gmail, ปฏิทิน และเอกสาร

ข้อจำกัด

ก่อนเริ่มการแปลง โปรดอ่านข้อจำกัดของส่วนเสริม Google Workspace ที่ขยาย Google Chat เพื่อให้มั่นใจว่าแอป Google Chat จะแปลงได้โดยไม่สูญเสียฟังก์ชันที่จำเป็น

ขั้นตอนที่ 1: คัดลอกโค้ดแอป Google Chat ที่มีอยู่

กระบวนการ Conversion ต้องมีการเปลี่ยนแปลงโค้ด หากไม่ต้องการให้แอป Google Chat ที่ใช้งานจริงได้รับผลกระทบ ให้สร้างและทำงานกับสำเนาของโค้ด

ขั้นตอนที่ 2: แก้ไขโค้ดที่คัดลอก

ส่วนเสริมของ Google Workspace ที่ขยายการใช้งาน Google Chat จะใช้โครงสร้างคำขอและ การตอบกลับที่แตกต่างจากแอป Google Chat ที่สร้างขึ้นด้วย เหตุการณ์การโต้ตอบของ Chat API คุณต้อง อัปเดตโค้ดเพื่อใช้ส่วนเสริม Google Workspace EventObject แทน Event ของ Google Chat API สำหรับคำขอและการตอบกลับ ใช้คำแนะนำในการแปลงโค้ดเพื่อแก้ไขโค้ด

ขั้นตอนที่ 3: เปิดใช้การกำหนดค่าส่วนเสริมของ Google Workspace สำหรับผู้ใช้ทดสอบ

ใช้คอนโซล Google Cloud เพื่อกำหนดการตั้งค่าส่วนเสริม Google Workspace สำหรับแอป Google Chat ของคุณ

1. ไปที่หน้าการกำหนดค่า Google Chat API ในคอนโซล Google Cloud

   ไปที่หน้าการกำหนดค่า Google Chat API

2. ในส่วนฟีเจอร์แบบอินเทอร์แอกทีฟ ให้เปิดเปิดใช้ฟีเจอร์แบบอินเทอร์แอกทีฟ

3. ในส่วนแปลงเป็นส่วนเสริมของ Google Workspace ให้คลิกแปลงเป็นส่วนเสริม

4. เปิดใช้เปิดการตั้งค่าการกำหนดค่าส่วนเสริม

5. ในส่วนระดับการมองเห็น ให้เพิ่มอีเมลของผู้ใช้ทดสอบ

6. หากจำเป็น ให้อัปเดตการตั้งค่าการเชื่อมต่อด้วย URL ของปลายทางการติดตั้งใช้งานหรือรหัสการติดตั้งใช้งาน Apps Script ของโค้ดแอป Google Chat ที่คัดลอกและแก้ไขจากขั้นตอนที่ 2

7. คลิกบันทึกและทดสอบ

ขั้นตอนที่ 4: ทดสอบแอปที่แปลงแล้ว

ทดสอบฟังก์ชันการทำงานของส่วนเสริม Google Workspace อย่างละเอียดโดยใช้บัญชีผู้ใช้ทดสอบที่กำหนดค่าไว้ในขั้นตอนที่ 3 ยืนยันฟีเจอร์และการโต้ตอบทั้งหมด

ขั้นตอนที่ 5: ทำ Conversion ให้เสร็จสมบูรณ์สำหรับผู้ใช้ทั้งหมด

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

1. ไปที่หน้าการกำหนดค่า Google Chat API ในคอนโซล Google Cloud

   ไปที่หน้าการกำหนดค่า Google Chat API

2. คลิกแปลงเป็นส่วนเสริมในส่วนฟีเจอร์แบบอินเทอร์แอกทีฟ แผงด้านข้างจะเปิดขึ้น

3. คลิกแปลงเป็นส่วนเสริมในแผงด้านข้าง

4. พิมพ์รหัสโปรเจ็กต์ แล้วคลิกแปลง

ตอนนี้แอป Google Chat ของคุณเป็นส่วนเสริมของ Google Workspace ที่ขยาย Google Chat

ไม่บังคับ: ล้างข้อมูลหรือปล่อยทรัพยากร Google Cloud ที่ไม่ได้ใช้

ไม่บังคับ: หลังจากแปลงแอป Google Chat เป็น ส่วนเสริมของ Google Workspace แล้ว หากต้องการหลีกเลี่ยง การเรียกเก็บเงินจากบัญชี Google Cloud สำหรับทรัพยากรที่แอป Google Chat ใช้ซึ่งไม่ได้ใช้งานแล้ว ให้พิจารณาปิดทรัพยากรเหล่านั้น

คู่มือการแปลงโค้ด

ส่วนนี้จะอธิบายรายละเอียดการแมประหว่างรูปแบบการโต้ตอบของ Google Chat API Event กับรูปแบบของส่วนเสริม Google Workspace EventObject

การแมปคำขอ

ตารางต่อไปนี้แสดงวิธีที่ฟิลด์ใน Google Chat API Event แมปกับฟิลด์ที่เกี่ยวข้องในส่วนเสริม Google Workspace EventObject

ขอการแมปตามกรณีการใช้งาน

ตารางต่อไปนี้แสดงความแตกต่างในเพย์โหลดคำขอสำหรับกรณีการใช้งานทั่วไป ระหว่างแอป Google Chat ที่สร้างขึ้นด้วยเหตุการณ์การโต้ตอบของ Chat API กับส่วนเสริมของ Google Workspace ที่ขยาย Google Chat

{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}

{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}

{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}

{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}

{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}

{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}

{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}

{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}

{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}

{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}

{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}

{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}

{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}

{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}

{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}

{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}

{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}

{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}

{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}

{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

การแมปการตอบกลับตามกรณีการใช้งาน

ส่วนเสริม Google Workspace ที่ขยาย Google Chat จะแสดงผลการดำเนินการแทนออบเจ็กต์ Message ตารางต่อไปนี้จะจับคู่Messageประเภทการตอบกลับ ของ Google Chat API กับการดำเนินการที่เทียบเท่าในส่วนเสริม Google Workspace

{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}

{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

จัดการการโต้ตอบกับบัตรในข้อความที่สร้างขึ้นก่อน Conversion

เมื่อแปลงแอป Google Chat ที่ใช้ HTTP เป็น ส่วนเสริมของ Google Workspace การโต้ตอบกับการ์ดในข้อความที่สร้างขึ้นก่อน การแปลงจะต้องมีการจัดการเป็นพิเศษ ส่วนเสริมจะใช้ URL แบบ HTTP เต็มสำหรับ action.function ของการ์ด ขณะที่แอป Chat ที่สร้างด้วย เหตุการณ์การโต้ตอบของ Google Chat API จะใช้ชื่อฟังก์ชัน ตารางต่อไปนี้ สรุปความแตกต่างเหล่านี้

{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}

{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

หากต้องการให้การโต้ตอบกับการ์ดทํางานได้สําหรับข้อความที่สร้างขึ้นก่อน Conversion ให้กําหนดค่าURL การโต้ตอบกับการ์ดในหน้าการกําหนดค่า Google Chat API

URL นี้ใช้สำหรับการโต้ตอบในข้อความที่สร้างขึ้นก่อนที่คุณจะแปลงแอปเท่านั้น เมื่อผู้ใช้โต้ตอบกับข้อความใดข้อความหนึ่งเหล่านี้ ระบบจะส่งค่า action.function เดิมเป็นพารามิเตอร์ที่ชื่อ __action_method_name__

ตัวอย่าง: การคลิกการ์ด

หากคุณกำหนดค่า URL การโต้ตอบกับการ์ดเป็น https://.../card-interaction-handler และผู้ใช้คลิกการ์ดในข้อความที่ผ่านมาพร้อมการดำเนินการต่อไปนี้

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

ระบบจะส่งเหตุการณ์ไปยัง Card Interaction URL ที่กำหนดค่าไว้ในรูปแบบต่อไปนี้

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

ตัวอย่าง: เมนูแบบเลือกหลายรายการ

หากผู้ใช้โต้ตอบกับเมนูแบบเลือกหลายรายการที่มีแหล่งข้อมูลภายนอก จะเกิดสิ่งต่อไปนี้

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

ระบบจะส่งเหตุการณ์ไปยัง Card Interaction URL ที่กำหนดค่าไว้ในรูปแบบต่อไปนี้

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

หากเปิดใช้ URL ปลายทาง HTTP ทั่วไปสำหรับทริกเกอร์ทั้งหมดสำหรับทริกเกอร์ HTTP ระบบจะใช้ URL ทั่วไปสำหรับเหตุการณ์คลิกปุ่มด้วย

ยืนยันคำขอสำหรับส่วนเสริม HTTP ของ Google Workspace ที่ขยาย Chat

สำหรับแอป Google Chat ที่ใช้ HTTP คุณจะต้องอัปเดตตรรกะเพื่อยืนยันว่าคำขอมาจาก Google เมื่อแปลงเป็นส่วนเสริมของ Google Workspace

• การยืนยันแอป Google Chat ผ่าน HTTP สำหรับเหตุการณ์การโต้ตอบของ Google Chat API: ยืนยันคำขอจาก Google Chat
• การยืนยัน HTTP ของส่วนเสริม Google Workspace: การยืนยันคำขอจาก Google

ความแตกต่างที่สำคัญในการยืนยันคำขอมีดังนี้

คุณดูอีเมลของบัญชีบริการที่ไม่ซ้ำกันสำหรับส่วนเสริม Google Workspace ได้ในส่วนแปลงเป็นส่วนเสริม Google Workspace ในหน้าการกำหนดค่า Google Chat API ในคอนโซล Google Cloud

วิธียืนยันคำขอในส่วนเสริม Google Workspace ที่อัปเกรดแล้ว

1. หากใช้ฟังก์ชัน Cloud Run ให้มอบบทบาท roles/cloudfunctions.invoker ให้กับบัญชีบริการต่อส่วนเสริม ดูให้สิทธิ์เข้าถึงด้วย IAM
2. อัปเดตรหัสยืนยันโทเค็นเพื่อใช้อีเมลของบัญชีบริการของส่วนเสริม Google Workspace เพื่อยืนยันลายเซ็นของโทเค็นสำหรับผู้ถือ ดูตรวจสอบคำขอจาก Google