Bu rehber, Actions projesi geliştirme sürecinde size yol gösterir bir iş ortağıdır.
İşlem akışı
Actions projeniz rezervasyonları işlediğinde şu akışı kullanır:
- İşlem gereksinimlerini doğrulama (isteğe bağlı): İşlemleri kullanın görüşmenin başında kullanıcılarınızın ihtiyaçlarının kullanıcı bir işlem gerçekleştirebilir.
- Siparişi oluşturun: Kullanıcıyı, nasıl bir sipariş "alışveriş sepeti montajı" rezervasyonun ayrıntılarını oluşturdukları bölüm.
- Sipariş önerme - "Alışveriş sepeti" baştan sona rezervasyon yapmayı önerin. - Böylece doğru olduğunu onaylayabilir. Rezervasyon onaylanırsa Rezervasyon ayrıntılarını içeren bir yanıt almak istiyorum.
- Siparişi son haline getirin ve makbuz gönderin: Sipariş onaylandıktan sonra kullanıcıya bir makbuz göndermemizi sağlar.
- Sipariş güncellemeleri gönderin: Rezervasyonun kullanım ömrü süresince kullanıcının rezervasyon durumu güncellemelerini Siparişler API'si.
Kısıtlamalar ve inceleme kuralları
Şunu kullanan İşlemler için ek politikaların geçerli olduğunu unutmayın: işlemler ve Siparişler API'si. İşlemler'i incelememiz altı haftayı bulabilir Bu nedenle yayın planınızı planlarken bu zamanı da hesaba katın. İnceleme sürecini kolaylaştırmak için işlemlerle ilgili politikalar ve kurallar incelemenizi öneririz.
Orders API'yi kullanan Actions (İşlemler) özelliğini yalnızca şu ülkelerde dağıtabilirsiniz:
|
Avustralya Brezilya Kanada Endonezya |
Japonya Meksika Katar Rusya |
Singapur İsviçre Tayland Türkiye Birleşik Krallık Amerika Birleşik Devletleri |
Projenizi oluşturma
İşlem görüşmelerinin kapsamlı bir örneği için İşlemler Node.js'deki örnek.
Kurulum
İşleminizi oluştururken işlem gerçekleştirmek istediğinizi belirtmeniz gerekir Actions Console'da görüntüleyebilirsiniz.
Projenizi ve sipariş karşılamayı ayarlamak için şunları yapın:
- Yeni proje oluşturun veya mevcut bir projeyi içe aktarın.
- Dağıt > Dizin bilgileri.
Ek bilgiler > İşlemler > "İşlemlerinizi Yapın" ifadesinin bulunduğu kutuyu işaretleyin İşlemler API'sini nasıl kullanıyor?
İşlem gereksinimlerini doğrulayın (isteğe bağlı)
Kullanıcı rezervasyon yapmak istediğini belirtir gelmez rezervasyon yapabiliyorlar. Örneğin, İşleminiz çağrıldığında "Oturma vakti ayarlamak ister misiniz?" diye sorun. Kullanıcı "evet" derse devam edebilmelerini ve tüm ayarları düzeltme fırsatı vermelerini sağlamalısınız. ve işleme devam etmesini engelleyebilir. Bunun için: gerçekleştirildiğini kontrol etmek sizin görevinizdir.
İşlem Gereksinimleri Kontrol sahnesi oluşturma
- Sahneler sekmesinden şu adla yeni bir sahne ekleyin:
TransactionRequirementsCheck. - Alan doldurma altında, yeni bir aralık eklemek için + simgesini tıklayın.
- Tür seçin bölümünde
actions.type.TransactionRequirementsCheckResult'yi seçin. seçeneğini belirleyin. - Alan adı alanında, alana
TransactionRequirementsCheckadını verin. - Alan değeri geri yazmayı özelleştir onay kutusunu etkinleştirin (varsayılan olarak etkindir).
Kaydet'i tıklayın.
İşlem şartları denetimi aşağıdaki sonuçlardan biriyle sonuçlanır:
- Koşullar karşılanırsa oturum parametresi başarıyla ayarlanır ve kullanıcının siparişini oluşturmaya devam edebilirsiniz.
- Koşullardan biri veya daha fazlası karşılanamazsa oturum parametresi
bir hata koşuluyla ayarlanır. Bu durumda konuşmanın yönünü
veya görüşmeyi sonlandırmanız gerekebilir.
- Başarısız duruma neden olan hatalar kullanıcı tarafından düzeltilebiliyorsa cihazlarında bu sorunları çözmeleri istenir. Öğe yalnızca ses içeren bir yüzeyde yer alıyorsa kullanıcının telefonuna başlatılmalıdır.
İşlem Koşulları Kontrolü'nün sonucunu işleme
- Sahneler sekmesinden yeni oluşturduğunuzu seçin.
TransactionRequirementsChecksahne. - Koşul altında, yeni bir koşul eklemek için + simgesini tıklayın.
Metin alanına, başarı koşulu:
scene.slots.status == "FINAL" && session.params.TransactionRequirementsCheck.resultType == "CAN_TRANSACT"İmlecinizi yeni eklediğiniz koşulun üzerine getirin ve yukarı oku tıklayın
if scene.slots.status == "FINAL"öncesine yerleştireceğiz.İstemleri gönder'i etkinleştirin ve kullanıcıyı bilgilendiren basit bir istem sağlayın bir işlem yapmaya hazır olduğundan emin olun.
candidates: - first_simple: variants: - speech: >- Looks like you're good to go!.Transition bölümünde, kullanıcının devam etmesine izin veren başka bir sahne seçin ve işleme devam edebilirsiniz.
Koşulu
else if scene.slots.status == "FINAL"seçin.İstemleri gönder'i etkinleştirin ve kullanıcıyı bilgilendiren basit bir istem sağlayın işlem yapamazlarsa:
candidates: - first_simple: variants: - speech: Transaction requirements check failed.Görüşmeyi sonlandırmak için Geçiş bölümünde Görüşmeyi sonlandır'ı seçin Kullanıcı işlem yapamıyorsa.
Siparişi oluşturma
İhtiyacınız olan kullanıcı bilgilerini edindikten sonra, "montaj" kullanıcılara rezervasyonlarını yapma konusunda rehberlik eden bir deneyimdir. Hepsini İşlemin, müşterinin ihtiyaçlarına uygun olarak biraz farklı bir alışveriş sepeti montaj akışı olacaktır geliştirmenizi sağlar.
Temel alışveriş sepeti montaj deneyiminde, kullanıcı eklemek için listeden seçenek belirler. ancak bu sayede görüşmeyi basitleştirecek, en iyi uygulamaları paylaşacağız. Örneğin, müşterilerin uzun süre alışveriş yapmasına olanak tanıyan bir alışveriş sepeti kullanıcının basit bir evet veya hayır sorusuyla aylık rezervasyon yapmasını sağlayabilir. Ayrıca kullanıcıya "önerilen" bandında veya liste kartı da sunabilirsiniz sağlayabilir.
Şu veriler için zengin yanıtlar kullanmanızı öneririz: kullanıcının seçeneklerini görsel olarak sunmanın yanı sıra görüşmeyi kullanıcılar yalnızca sesini kullanarak alışveriş sepetini oluşturabiliyor. Bazı en iyi uygulamaları ve alışveriş sepeti montaj deneyimlerine ilişkin örnekler için Tasarım yönergelerine bakın.
Sipariş oluşturun
Görüşmeniz boyunca kullanıcının rezervasyon bilgilerini toplayın, ardından
bir Order nesnesi oluşturun.
Order, en azından şunları içermelidir:
buyerInfo: Satın alma işlemini yapan kullanıcıyla ilgili bilgiler.transactionMerchant: Siparişi kolaylaştıran satıcıyla ilgili bilgiler.contents-lineItemsolarak listelenen siparişin asıl içeriği.
Daha fazla bilgi için Order
yanıt dokümanlarına göz atın. Proje başlatma belgesine
farklı alanları görüntüleyebilirsiniz.
Aşağıdaki örnek kod, isteğe bağlı alanlar da dahil olmak üzere eksiksiz bir rezervasyon siparişini gösterir:
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'
};
Sipariş ve sunu seçenekleri oluşturma
const orderOptions = {
'requestDeliveryAddress': false,
};
const presentationOptions = {
'actionDisplayName': 'RESERVE'
};
Sipariş verilerini oturum parametresine kaydet
Sipariş karşılamadaki sipariş verilerini bir oturum parametresine kaydedin. Sipariş nesne aynı oturumdaki sahnelerde kullanılır.
conv.session.params.order = {
'@type': 'type.googleapis.com/google.actions.transactions.v3.TransactionDecisionValueSpec',
order: order,
orderOptions: orderOptions,
presentationOptions: presentationOptions
};
Siparişi teklif et
Bir rezervasyon siparişi oluşturduktan sonra bunu kullanıcıya sunmanız gerekir: onaylayın veya reddedin. Bunu yapmak için işlem gerçekleştiren bir sahneye geçmeniz gerekir düşünülebilir.
İşlem Karar sahnesi oluşturma
- Sahneler sekmesinden
TransactionDecisionadlı yeni bir sahne ekleyin. - Alan doldurma altında, yeni bir aralık eklemek için + simgesini tıklayın.
- Tür seçin altında, şu şekilde
actions.type.TransactionDecisionValueseçin: zaman aralığı türü. - Alan adı alanında, alana
TransactionDecisionadını verin. - Alan değeri geri yazmayı özelleştir onay kutusunu etkinleştirin (varsayılan olarak etkindir).
- Alanı yapılandır'ın altında, açılır listeden Oturum parametresini kullan'ı seçin.
- Alanı yapılandır altında,şu işlemle kullanılan oturum parametresinin adını girin:
siparişi metin alanına (
$session.params.order) kaydedin. Kaydet'i tıklayın.
Asistan, TransactionDecisionValue boşluklarından birini doldurmak için aşağıdaki işlemleri başlatır
aktardığınız Order öğesinin doğrudan oluşturulduğu yerleşik bir deneyimdir
"alışveriş sepeti önizleme kartı" ekleyebilirsiniz. Kullanıcı "rezervasyon planla" diyebilir, işlemi reddedebilir,
veya rezervasyon ayrıntılarını değiştirme isteğinde bulunun.
Bu noktada kullanıcı siparişte değişiklik isteğinde de bulunabilir. Böyle durumlarda sipariş karşılama isteğinizin şu tarihten sonra işleyebildiğinden emin olmalıdır: alışveriş sepeti montaj deneyimini tamamladıktan sonra yapabilirsiniz.
İşlem Karar sonucunu işleme
TransactionDecisionValue alanı doldurulduğunda, kullanıcının
işlem kararı bir oturum parametresinde saklanır. Bu değer şunları içerir:
şu:
ORDER_ACCEPTED,ORDER_REJECTED,CART_CHANGE_REQUESTEDUSER_CANNOT_TRANSACT.
Bir işlem kararı sonucunu işlemek için:
- Sahneler sekmesinden, yeni oluşturduğunuz
TransactionDecisionsahnesini seçin. - Koşul altında, yeni bir koşul eklemek için + simgesini tıklayın.
Metin alanına, başarı koşulu:
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"İmlecinizi yeni eklediğiniz koşulun üzerine getirin ve yukarı oku tıklayın
if scene.slots.status == "FINAL"öncesine yerleştireceğiz.İstemleri gönder'i etkinleştirin ve kullanıcıyı bilgilendiren basit bir istem sağlayın müşterinin rezervasyonunu tamamladığında:
candidates: - first_simple: variants: - speech: >- Transaction completed! Your reservation $session.params.TransactionDecision.order.merchantOrderId is all set!Görüşmeyi sonlandırmak için Geçiş bölümünde Görüşmeyi sonlandır'ı seçin.
Koşul altında, yeni bir koşul eklemek için + simgesini tıklayın.
Metin alanına, hata koşulları:
scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_REJECTED"İmlecinizi yeni eklediğiniz koşulun üzerine getirin ve yukarı oku tıklayın
if scene.slots.status == "FINAL"öncesine yerleştireceğiz.İstemleri gönder'i etkinleştirin ve kullanıcıya sipariş reddedildi:
candidates: - first_simple: variants: - speech: Looks like you don't want to set up a reservation. Goodbye.Görüşmeyi sonlandırmak için Geçiş bölümünde Görüşmeyi sonlandır'ı seçin.
Koşulu
else if scene.slots.status == "FINAL"seçin.İstemleri gönder'i etkinleştirin ve kullanıcıyı bilgilendiren basit bir istem sağlayın işlem yapamazlarsa:
candidates: - first_simple: variants: - speech: >- Transaction failed with status $session.params.TransactionDecision.transactionDecisionGörüşmeyi sonlandırmak için Geçiş bölümünde Görüşmeyi sonlandır'ı seçin Kullanıcı işlem yapamıyorsa.
Rezervasyonu tamamlama ve makbuz gönderme
TransactionDecisionValue alanı ORDER_ACCEPTED sonucu döndürdüğünde,
projeyi planlamak için gereken tüm işleme
(örneğin kendi veritabanınızda saklama)
Sohbeti devam ettirmek için basit bir yanıt gönderin. Kullanıcı bir "daraltılmış makbuz kartı" yanıtınızı gönderin.
İlk sipariş güncellemesini göndermek için:
- Sahneler sekmesinden
TransactionDecisionsahnenizi seçin. Koşul bölümünde, başarılı sonucu kontrol eden koşulu seçin.
ORDER_ACCEPTED:scene.slots.status == "FINAL" && session.params.TransactionDecision.transactionDecision == "ORDER_ACCEPTED"Bu koşul için Webhook'unuzu arama'yı etkinleştirin ve bir intent sağlayın işleyici adını (ör.
update_order) girin.
Webhook kodunuzda, ilk sipariş güncellemesi göndermek için intent işleyici ekleyin:
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' })); });
Sipariş güncellemelerini gönderin
Rezervasyon durumu, kullanım ömrü boyunca değişir. Kullanıcıyı gönderin Orders API'ye yapılan HTTP PATCH istekleriyle yapılan rezervasyon siparişi güncellemelerinin sipariş durumunu ve ayrıntılarını görebilirsiniz.
Orders API'ye eşzamansız istekler oluşturma
Orders API'ye yapılan sipariş güncelleme istekleri, bir erişim tarafından yetkilendirilir
jeton. Orders API'ye sipariş güncellemesi yamalamak için bir JSON dosyası indirin
Actions Console projenizle ilişkilendirilmiş hizmet hesabı anahtarını seçin, ardından
bir hamiline ait jeton hizmet hesabı anahtarı ile
HTTP isteğinin Authorization başlığı.
Hizmet hesabı anahtarınızı almak için aşağıdaki adımları uygulayın:
- Google Cloud Console'da Menü lastik düzeneği >'ne gidin API'ler ve Hizmetler > Kimlik Bilgileri > Kimlik bilgileri oluştur > Hizmet hesabı anahtarı.
- Service Account (Hizmet Hesabı) altında New Service Account (Yeni Hizmet Hesabı) seçeneğini belirleyin.
- Hizmet hesabını
service-accountolarak ayarlayın. - Rol öğesini Proje > olarak ayarlayın Sahibi.
- Anahtar türünü JSON olarak ayarlayın.
- Oluştur'u seçin.
- Yerel makinenize özel bir JSON hizmet hesabı anahtarı indirilir.
Sipariş güncellemeleri kodunuzda hizmet anahtarınızı hamiline ait jetonla değiştirin Google API'leri istemci kitaplığını ve "https://www.googleapis.com/auth/actions.order.developer" kapsamında yer alır. Daha fazla API istemci kitaplığındaki yükleme adımları ve örnekler GitHub sayfası.
Node.js örneğimizdeki order-update.js referansı
örnek bir anahtar değişimine bakalım.
Sipariş güncellemelerini gönderin
Hizmet hesabı anahtarınızı OAuth hamiline ait jetonla değiştirdikten sonra Siparişler API'ye yetkili YAMA istekleri olarak sipariş güncellemeleri.
Siparişler API'si URL'si:
PATCH https://actions.googleapis.com/v3/orders/${orderId}
İsteğinizde aşağıdaki başlıkları sağlayın:
- OAuth taşıyıcı jetonuyla
"Authorization: Bearer token"anahtar/değer çiftleriyle değiştirin. "Content-Type: application/json".
YAMA isteği, aşağıdaki biçimde bir JSON gövdesi almalıdır:
{ "orderUpdate": OrderUpdate }
OrderUpdate
nesne aşağıdaki üst düzey alanlardan oluşur:
updateMask: Güncellediğiniz siparişin alanları. Güncellemek için rezervasyon durumu, değerireservation.status, reservation.userVisibleStatusLabelolarak ayarlayın.order- Güncellemenin içeriği. değerini, güncellenenOrdernesnesine ayarlayın. Rezervasyonun durumunu (örneğin,"PENDING"-"FULFILLED") olduğunda, nesne şu alanları kullanın:merchantOrderId:Ordernesnenizde ayarladığınız kimlik.lastUpdateTime- Bu güncellemenin zaman damgası.purchase- Şunları içeren bir nesne:status-ReservationStatusolan siparişin durumu, Örneğin "CONFIRMED" veya "CANCELLED".userVisibleStatusLabel- İlgili ayrıntıları sağlayan, kullanıcıya yönelik bir etiket sipariş durumunu (ör. "Rezervasyonunuz onaylandı") görebilirsiniz.
userNotification(isteğe bağlı) - AuserNotificationnesne (bu güncelleme gönderildiğinde kullanıcının cihazında görüntülenebilecek). Not bu nesneyi eklemenin, cihazınızda bildirimin gösterileceğini garanti etmediği cihazıyla ilgilidir.
Aşağıdaki örnek kod,OrderUpdate
FULFILLED adlı iş ortağına ait rezervasyon siparişinin durumu:
// 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}`);
}
Rezervasyon durumunu ayarlama
Bir sipariş güncellemesinin ReservationStatus
siparişin mevcut durumunu açıklamalıdır. Güncellemenizin order.ReservationStatus bölümünde
alanında, aşağıdaki değerlerden birini kullanın:
PENDING- Rezervasyon "oluşturuldu" İşleminiz tarafından kullanılıyor ancak ek işlemler yapmasını sağlar.CONFIRMED- Rezervasyon, planlama arka ucunuzda onaylanmıştır.CANCELLED: Kullanıcı, rezervasyonunu iptal etti.FULFILLED- Kullanıcının rezervasyonu hizmet tarafından yerine getirildi.CHANGE_REQUESTED: Kullanıcı, rezervasyonda değişiklik isteğinde bulundu ve bu değişiklik bir şablondur.REJECTED- İşlemi gerçekleştiremediyseniz veya başka bir şekilde Rezervasyonu onaylayın.
Ürün veya hizmetinizle alakalı her durum için
daha fazla bilgi edineceksiniz. Örneğin, rezervasyonunuzun rezervasyonun manuel olarak işlenmesi gerekiyorsa
isteği aldıktan sonra rezervasyonu onayla, tarihine kadar PENDING siparişi güncellemesi gönder
gerektiğini unutmayın. Her rezervasyon için her durum değeri gerekmez.
Projenizi test etme
Projenizi test ederken Actions konsolunda korumalı alan modunu etkinleştirebilirsiniz ödeme yönteminden ödeme almadan İşleminizi test edin. Korumalı alan modunu etkinleştirmek için şu adımları uygulayın:
- Actions konsolundaki gezinme bölümünde Test'i tıklayın.
- Ayarlar'ı tıklayın.
- Geliştirme Korumalı Alanı seçeneğini etkinleştirin.
Fiziksel işlemler için, isInSandbox alanını true olarak ayarlayabilirsiniz.
örnekleminiz. Bu işlem,
Actions Console'da oturum açın. isInSandbox kullanan bir kod snippet'i görmek için
Sipariş güncellemelerini gönderin bölümü.
Sorun giderme
Test sırasında herhangi bir sorunla karşılaşırsanız sorun giderme adımlarımızı okuyun anlamına gelir.