Mengintegrasikan data menu menggunakan Food Ordering AI Agent API

Panduan ini menjelaskan cara menyusun, mengubah, dan menyerap data menu restoran Anda ke dalam Food Ordering AI Agent Menu API. Dengan melakukannya, Anda memungkinkan agen AI memahami penawaran menu Anda dan secara akurat menerima pesanan dari pelanggan.

Sebelum memulai

Sebelum Anda dapat menyerap dan mengelola menu menggunakan Food Ordering AI Agent API, pertama:

1. Aktifkan Food Ordering AI Agent API:

     gcloud services enable foodorderingaiagent.googleapis.com --project=PROJECT
   

2. Pastikan Anda memiliki izin IAM yang diperlukan. Berikan peran Identity and Access Management (IAM) berikut kepada pengguna atau akun layanan yang berinteraksi dengan API:

   • Admin Agen Pemesanan Makanan (roles/foodorderingaiagent.admin): Peran ini memberikan akses penuh untuk membuat, membaca, memperbarui, dan menghapus semua resource Agen AI Pemesanan Makanan, termasuk Merek, Toko, dan Menu.

   Anda dapat memberikan peran IAM menggunakan konsol Google Cloud , alat command line gcloud, atau IAM API. Untuk mengetahui informasi selengkapnya, lihat Memberikan peran IAM.

   Untuk memberikan peran menggunakan konsol Google Cloud :

   1. Di konsol Google Cloud , buka halaman IAM.
   2. Klik Tambahkan.
   3. Masukkan akun utama (email pengguna atau akun layanan).
   4. Pilih peran Admin Agen AI Pemesanan Makanan.
   5. Klik Simpan.

   Tanpa izin yang sesuai, panggilan API untuk membuat atau mengubah Merek, Toko, atau Menu akan ditolak. Peran Food Ordering Agent Viewer tidak cukup untuk tugas yang dijelaskan dalam panduan ini, karena hanya memberikan akses hanya baca.

Ringkasan

Food Ordering AI Agent Menu API dirancang agar fleksibel dan dapat mengakomodasi berbagai struktur menu, mulai dari daftar singkat item mandiri hingga menu kompleks dengan pengubah bertingkat dan makanan kombinasi. API ini dibuat berdasarkan beberapa konsep utama:

• Menu: Penampung tingkat teratas untuk semua entitas yang dapat dipesan.
• Item: Merepresentasikan produk tingkat teratas yang dapat dipesan dari menu, seperti makanan, hidangan utama, atau produk apa pun yang dapat dipesan secara terpisah. Item dapat mereferensikan ModifierGroup.
• ModifierGroup: Kumpulan opsi Modifier yang dapat diterapkan ke Item atau Modifier lain (memungkinkan penyusunan). Contohnya termasuk "Pilih Sisi Anda", "Tambahkan Topping", atau "Pilih Rasa Minuman".
• Pengubah: Setiap opsi dalam ModifierGroup, seperti "Kentang Goreng", "Keju Ekstra", atau "Cola". Pengubah dapat menyesuaikan harga dan juga dapat memiliki ModifierGroup bertingkatnya sendiri.
• MenuCategory: Digunakan untuk mengelola Item ke dalam bagian untuk ditampilkan dan dipahami (misalnya, "Appetizers", "Burgers", "Drinks").

Konsep dan struktur utama

Bagian ini menjelaskan komponen inti skema Food Ordering AI Agent Menu API dan cara penyusunannya. Memahami konsep ini sangat penting untuk memodelkan data menu Anda dengan benar.

Item

Setiap item berbeda dalam menu Anda harus ditentukan sebagai Item. Kolom utama meliputi:

• id: ID unik dalam menu.
• display_name: Nama yang ditampilkan kepada pelanggan.
• base_price: Harga dasar item.
• modifier_groups: Referensi ke ModifierGroup yang dapat berlaku untuk item ini.
• category_ids: Referensi ke ID MenuCategory yang menjadi bagian dari item ini.
• availability: Menentukan kapan item tersedia (misalnya, menurut status atau bagian hari). Jika tidak ditentukan, nilai defaultnya adalah STATUS_AVAILABLE.

Pengubah dan ModifierGroups

Pengubah memungkinkan penyesuaian item.

• ModifierGroup menentukan serangkaian pilihan, termasuk batasan seperti pilihan minimum atau maksimum. Harus berisi minimal satu Modifier.
• Modifiers mewakili opsi sebenarnya. price_adjustment dapat memiliki price_adjustment dan dapat mereferensikan ModifierGroup lain secara rekursif untuk penyesuaian bertingkat (misalnya, Item "Combo Makanan" dapat memiliki ModifierGroup "Pilih Minuman Anda", dan Modifier "Soda" dalam grup tersebut dapat memiliki ModifierGroup "Pilih Rasa").

Tips: Agen secara aktif bekerja dengan pelanggan untuk memenuhi batasan yang ditentukan dalam setiap ModifierGroup. Misalnya, jika Item (misalnya, "Fajitas untuk dua orang") merujuk ke ModifierGroup dengan min_selection_count 2 (misalnya, "Dua minuman"), dan pelanggan memesan Item tanpa menentukan pilihan untuk ModifierGroup tersebut (misalnya, "Saya ingin fajitas untuk dua orang"), agen akan bekerja sama dengan pelanggan untuk memenuhi batasan (misalnya, "Dua minuman apa yang Anda inginkan?").

Contoh 1: Topping

"Bacon Cheeseburger" Item dapat merujuk ke "Topping" ModifierGroup. ModifierGroup ini akan berisi Modifier seperti "Keju Ekstra", "Tanpa Bawang", dll.

Contoh 2: Makanan kombinasi (Combo)

Beberapa menu memiliki struktur kompleks yang terdiri dari beberapa pilihan bertingkat, seperti makanan kombinasi, atau "combo". Kombinasi dapat dimodelkan sebagai Item dengan beberapa ModifierGroup yang merepresentasikan komponen kombinasi. Misalnya, Item "Burger Combo", yang terdiri dari hidangan utama tetap yang dipaketkan dengan beberapa opsi untuk lauk dan minuman, dapat dimodelkan dengan:

• ModifierGroup untuk samping (misalnya, "Side choices").
  • Setiap opsi sisi dimodelkan sebagai Modifier (misalnya, "Kentang Goreng", "Salad").
    • Setiap opsi minuman dapat mereferensikan ModifierGroup bertingkat (misalnya, "Ice options", "Drink size") yang pada gilirannya mereferensikan Modifiers (misalnya, "No Ice", "Large drink").
• ModifierGroup untuk minuman (misalnya, "Minuman").
  • Setiap opsi minuman dimodelkan sebagai Modifier.
    • Setiap opsi minuman dapat mereferensikan ModifierGroup bertingkat (misalnya, "Opsi es", "Ukuran minuman") yang pada gilirannya mereferensikan Modifiers (misalnya, "Tanpa Es", "Minuman besar").
• ModifierGroup untuk topping pada hidangan utama. (mis., "Keju Ekstra", "Bacon").

Ketersediaan

Pesan Availability di Item dan Modifier memungkinkan Anda menentukan:

• status: STATUS_AVAILABLE, STATUS_OUT_OF_STOCK, dll.
• daypart_availability: Menautkan ke ID bagian waktu tertentu jika item hanya tersedia selama waktu tertentu (misalnya, "Breakfast Menu").

Atribut integrasi

Pesan Item, Modifier, dan ModifierGroup berisi kolom integration_attributes. Kolom ini (ItemIntegrationAttributes, ModifierIntegrationAttributes, dll.) menyimpan google.protobuf.Struct yang disebut custom_integration_attributes. Anda dapat menggunakan ini untuk menyimpan data nilai kunci arbitrer, seperti:

• ID dari sistem Tempat Penjualan (POS) Anda.
• SKU atau kode internal lainnya.
• Metadata lain yang diperlukan untuk pemrosesan pesanan downstream atau integrasi POS.

Data ini diteruskan secara buram oleh agen AI.

Label

Anda dapat menggunakan kolom labels pada resource Menu untuk melampirkan metadata ke menu guna membantu integrasi dan proses debug.

Label adalah fitur praktis dan tidak memengaruhi perilaku agen AI.

Tips: Anda dapat menggunakan label untuk memberi anotasi pada Menu dengan ID versi yang terkait, stempel waktu berlaku, atau URL tempat data menu diambil. Hal ini berguna untuk melacak kembali nuansa perilaku agen ke data sumber menu tertentu.

Membuat Menu

Menu dimasukkan menggunakan panggilan RPC CreateMenu dalam MenuService.

Langkah

1. Mengubah Data Anda: Konversi data menu yang ada (dari POS, API, atau sumber lain) ke dalam struktur yang ditentukan oleh pesan google.cloud.foodorderingaiagent.v1beta.Menu. Hal ini melibatkan pemetaan item, pengubah, kategori, dan harga ke jenis pesan API yang sesuai.
2. Buat CreateMenuRequest:
   • Tetapkan kolom parent (misalnya, projects/PROJECT/locations/LOCATION).
   • Isi kolom menu dengan objek Menu yang telah diubah.
   • (Opsional) berikan menu_id.
3. Panggil API: Kirim CreateMenuRequest ke endpoint MenuService.CreateMenu. API akan membersihkan menu terlebih dahulu, lalu memvalidasinya, dan menampilkan objek Menu akhir.
4. Menangani Pembaruan Menu: Setiap kali data sumber menu diperbarui (misalnya, saat produk baru diperkenalkan, atau saat produk tidak tersedia), Menu baru harus dibuat yang mencerminkan data sumber yang diperbarui, dengan mengikuti penanganan pembaruan menu.

Panduan untuk transformasi data

Logika spesifik untuk mentransformasi data menu Anda akan bergantung pada format dan struktur sistem sumber Anda (misalnya, POS API, skema database). Berikut pendekatan umumnya:

• Mengekspor Data: Dapatkan ekspor lengkap data menu Anda, termasuk semua item, pengubah, harga, dan hubungan.
• Memetakan Entitas:
  • Identifikasi entity yang sesuai dalam skema Food Ordering AI Agent API untuk setiap elemen dalam data sumber Anda. Misalnya, "item menu" POS Anda kemungkinan akan dipetakan ke objek Item. "Opsi pesanan" atau "add-on" akan dipetakan ke Modifier dan ModifierGroup.
  • Membangun hubungan menggunakan ID. Misalnya, tautkan Item ke ModifierGroup yang berlaku menggunakan kolom referensi modifier_groups.
• Menangani Struktur Bertingkat: Jika menu Anda memiliki pengubah bertingkat (misalnya, memilih rasa minuman untuk soda dalam makanan kombo), buat model ini dengan membuat Modifiers merujuk ke ModifierGroups lain.
• Isi Atribut: Isi kolom seperti display_name, base_price, price_adjustment, dan availability berdasarkan data sumber Anda.
• Sertakan ID POS: Yang terpenting, simpan ID POS atau sistem internal Anda untuk setiap item, pengubah, dan grup dalam kolom custom_integration_attributes. Dengan begitu, Anda dapat menerjemahkan Order yang dihasilkan oleh agen kembali ke representasi aplikasi Anda tentang pesanan akhir atau keranjang yang sedang dalam proses.
• Pembuatan skrip: Anda mungkin perlu menulis skrip (misalnya, di Python, Node.js, Go) untuk mengambil data dari sumber, melakukan transformasi, dan memanggil metode CreateMenu. Skrip ini akan menggunakan Google Cloud library klien untuk autentikasi dan interaksi API.

Alur Kerja Transformasi Konseptual:

Alur kerja ini menguraikan proses transformasi data menu dari sistem sumber ke format Food Ordering AI Agent API:

1. Mengekstrak dan Memetakan Kategori:
   • Identifikasi kategori atau bagian dalam data sumber Anda (misalnya, "Appetizers", "Entrees").
   • Ubah setiap item menjadi objek MenuCategory dengan id dan display_name yang unik.
2. Ekstrak dan Petakan Item:
   • Identifikasi item yang dapat dijual di data sumber Anda.
   • Ubah setiap objek menjadi objek Item, dengan mengisi id, display_name, base_price, dan availability.
   • Petakan setiap Item ke kategorinya menggunakan kolom category_ids.
   • Simpan ID sistem sumber (seperti PLU atau SKU) di item.integration_attributes.custom_integration_attributes.
3. Mengekstrak dan Memetakan Pengubah:
   • Identifikasi penyesuaian, opsi, atau add-on item dalam data sumber Anda.
   • Mengelompokkan opsi terkait (misalnya, "Side Options", "Drink Choices", "Extra Toppings") menjadi objek ModifierGroup. Tentukan aturan pemilihan minimum dan maksimum pada setiap ModifierGroup.
   • Mengubah setiap opsi individual (misalnya, "Kentang Goreng", "Cola", "Keju Ekstra") ke dalam objek Modifier dalam ModifierGroup yang sesuai. Isi price_adjustment jika ada.
   • Simpan ID sistem sumber di modifier_group.integration_attributes.custom_integration_attributes dan modifier.integration_attributes.custom_integration_attributes.
4. Membangun Hubungan:
   • Untuk setiap Item, isi kolom modifier_groups-nya dengan referensi ke id dari ModifierGroup yang berlaku untuknya.
   • Jika Modifier memungkinkan penyesuaian lebih lanjut (misalnya, memilih rasa untuk pengubah "Soda"), isi kolom modifier_groups-nya untuk membuat pengubah bertingkat.
5. Menyusun dan Memasukkan:
   • Gabungkan semua objek MenuCategory, Item, ModifierGroup, dan Modifier ke dalam daftar dalam satu pesan Menu.
   • Panggil RPC CreateMenu dengan pesan Menu yang telah dirakit sepenuhnya sebagai input.

Menangani pembaruan menu

Menu bersifat tidak dapat diubah. Setelah dibuat menggunakan panggilan RPC CreateMenu, menu tidak dapat diubah. Untuk menyebarkan pembaruan menu ke dalam menu—seperti mengubah harga item, mengubah opsi, atau menyesuaikan ketersediaan—Anda harus membuat resource menu baru dengan memanggil CreateMenu lagi. Setiap versi menu Anda harus di-ingest sebagai resource Menu baru dengan menu_id unik.

Proses untuk menyerap versi baru menu sama dengan menyerap menu untuk pertama kalinya, dan melalui langkah-langkah pembersihan dan validasi yang sama. Saat menangani pesanan, perilaku agen akan selalu mencerminkan Menu yang baru saja dibuat yang terkait dengan Store yang dirujuk dalam konfigurasi sesi.

Tips: Label adalah cara yang berguna untuk mengatribusikan metadata yang membedakan Menu terkait. Mendiagnosis masalah operasional sering kali lebih mudah jika setiap Menu diberi anotasi dengan informasi yang mengidentifikasi peristiwa yang memicu pembuatannya dan informasi yang mengidentifikasi sumber kontennya.

Pembersihan menu otomatis

CreateMenu API secara otomatis melakukan beberapa langkah pembersihan untuk memperbaiki masalah umum dan memastikan konten menu ditampilkan secara konsisten di seluruh API. Validasi diterapkan setelah pembersihan ini untuk menyederhanakan integrasi menu bagi klien:

• Ketersediaan default: Item dan Modifier tanpa Availability.Status eksplisit ditetapkan ke STATUS_AVAILABLE.
• Hapus entity yang tidak dirujuk: Modifier dan ModifierGroup yang tidak dirujuk secara transitif oleh Item mana pun akan dihapus dari menu, karena tidak dapat dipesan.
• Menghapus grup pengubah yang kosong: ModifierGroup yang tidak berisi modifier_ids akan dihapus, dan semua referensi ke grup tersebut akan dihapus.

Validasi menu

Setelah pembersihan, API memvalidasi menu berdasarkan serangkaian aturan ketat untuk memastikan menu tersebut terbentuk dengan baik dan dapat digunakan secara andal oleh agen AI. Jika validasi gagal, panggilan CreateMenu akan menampilkan error yang menjelaskan masalahnya. Validasi utama meliputi:

• Kolom wajib diisi: Memastikan semua kolom wajib diisi seperti id, display_name, dan availability.status ada.
• ID Unik: Semua Item, Modifier, dan ModifierGroup harus memiliki ID unik dalam menu.
• Nama tampilan unik:
  • Semua Item harus memiliki display_name unik.
  • Dalam ModifierGroup tertentu, semua Modifier yang ada di dalamnya harus memiliki display_name unik.
• Integritas referensi:
  • Semua modifier_group_ids yang direferensikan oleh Item atau Modifier harus ada di menu.
  • Semua modifier_ids yang dirujuk oleh ModifierGroup harus ada di menu.
  • Pengubah default yang ditentukan dalam ModifierGroupReference harus ada dalam ModifierGroup yang dirujuk.
  • Jika Modifier menggunakan item_id untuk mereferensikan Item, Item tersebut harus ada.
• Batasan grup pengubah:
  • ModifierGroup tidak boleh kosong.
  • Jumlah pilihan minimum atau maksimum dalam ModifierGroups diperiksa konsistensi logisnya.
  • Tingkat Item atau Modifier modifier_constraints divalidasi terhadap batasan jumlah pilihan ModifierGroup yang dirujuk untuk memastikan bahwa batasan tersebut dapat dipenuhi.
• Kedalaman bertingkat: Kedalaman pengubah bertingkat dibatasi (misalnya, Item -> ModifierGroup -> Modifier -> ModifierGroup -> Modifier...) hingga maksimum 5 level.
• Validasi daypart: Jika daypart digunakan dalam Availability, daypart tersebut harus ditentukan dalam resource Store terkait.
• Referensi item pengubah: Modifier yang mereferensikan Item menggunakan item_id tidak boleh memiliki kolom seperti display_name atau availability yang ditetapkan, karena kolom ini diwarisi dari Item yang direferensikan.

Kegagalan pada salah satu aturan validasi ini akan mencegah menu dibuat atau diperbarui. Pesan error akan memberikan detail tentang entitas mana yang menyebabkan pelanggaran.

Referensi API

Untuk mengetahui detail lengkap tentang semua pesan dan kolom, lihat Referensi RPC Food Ordering AI Agent API.

Praktik terbaik

• ID Unik: Pastikan semua kolom id dalam cakupan Menu (untuk Item, Modifier, ModifierGroup, MenuCategory) bersifat unik.
• Nama yang Jelas: Gunakan display_names yang jelas dan mudah dipahami pelanggan. Berikan display_name yang berbeda untuk produk yang berbeda secara semantik guna mengarahkan agen untuk membedakan dengan tepat.
• Kombinasikan Model Secara Efektif: Modelkan makanan kombinasi sebagai Item dengan ModifierGroup yang merepresentasikan lauk, minuman, dan pilihan lainnya, seperti yang dijelaskan dalam makanan kombinasi. Hal ini memastikan agen dapat memandu pelanggan dengan benar melalui pilihan kombo.
• Gunakan Atribut Integrasi: Simpan ID sistem internal atau POS yang diperlukan di custom_integration_attributes untuk memfasilitasi integrasi pesanan yang lancar.
• Mengelola Ketersediaan: Pastikan status Availability selalu terbaru.
• Uji Secara Menyeluruh: Setelah penyerapan, uji pemahaman agen tentang menu dengan berbagai kombinasi pesanan.