1. Başlamadan önce
Akıllı ev entegrasyonları, Google Asistan'ın kullanıcıların evlerindeki bağlı cihazları kontrol etmesine olanak tanır. Akıllı ev İşlemi derlemek için akıllı ev amaçlarını işleyebilen bir Cloud webhook uç noktası sağlamanız gerekir. Örneğin, bir kullanıcı "Ok Google, ışıkları aç" dediğinde Asistan, cihazın durumunu güncellemek için bu komutu bulut karşılama aracınıza gönderir.
Yerel Ev SDK'sı, akıllı ev amaçlarını doğrudan bir Google Home cihazına yönlendiren yerel bir yol ekleyerek akıllı ev entegrasyonunuzu geliştirir. Bu yöntem, güvenilirliği artırır ve kullanıcıların komutlarının işlenmesinde gecikmeyi azaltır. Cihazları tanımlayan ve herhangi bir Google Home akıllı hoparlörde ya da Google Nest akıllı ekranda komut yürüten TypeScript veya JavaScript ile yerel bir istek karşılama uygulaması yazıp dağıtmanıza olanak tanır. Ardından uygulamanız, komutları yerine getirmek için mevcut standart protokolleri kullanarak yerel ağ üzerinden kullanıcıların mevcut akıllı cihazlarıyla doğrudan iletişim kurar.
Akıllı Ev İşlemleri'nde hata ayıklama, Actions'ınızı üretim kalitesiyle geliştirmenin önemli bir adımıdır. Ancak bilgilendirici, kullanımı kolay sorun giderme ve test araçları olmadan hem zorlayıcı hem de zaman alan bir süreçtir. Akıllı ev işlemleri için hata ayıklamayı kolaylaştırmak amacıyla, Actions'daki sorunları tespit edip çözmenize yardımcı olacak Google Cloud Platform (GCP) Metrikler, Logging ve Akıllı ev için Test Paketi kullanılabilir.
Ön koşullar
- Akıllı ev işlemi oluşturma geliştirici kılavuzu
- Akıllı ev işlemleri için yerel istek karşılamayı etkinleştir codelab'ini çalıştırın
Neler derleyeceksiniz?
Bu codelab'de, akıllı ev işlemleri için yerel bir sipariş karşılama sistemi oluşturup Asistan'a bağlayacak, ardından akıllı ev ve Google Cloud Platform (GCP) metrikleri ve günlük kaydı için Test paketi aracılığıyla Yerel Ev uygulamasının hatalarını ayıklayacaksınız.
Neler öğreneceksiniz?
- Üretim sorunlarını tespit edip çözmek için GCP Metrikleri ve Logging'i kullanma.
- İşlevsel sorunları ve API sorunlarını tanımlamak için Test Paketi'ni kullanma.
- Yerel Ev uygulamanızı geliştirirken Chrome Geliştirici Araçları'nı kullanma.
Gerekenler
- Google Chrome'un en son sürümü
- Google Home uygulamasının yüklü olduğu bir iOS veya Android cihaz
- Google Home akıllı hoparlörü veya Google Nest akıllı ekran
- Node.js 10.16 veya sonraki sürümler
- Bir Google Hesabı
- Google Cloud faturalandırma hesabı
2. Çamaşır makinesi uygulamasını çalıştır
Kaynak kodunu alma
Bu codelab örneğini geliştirme makinenize indirmek için aşağıdaki bağlantıyı tıklayın:
...veya komut satırından GitHub deposunu klonlayabilirsiniz:
$ git clone https://github.com/google-home/smarthome-debug-local.git
Proje hakkında
Başlangıç uygulaması, Akıllı ev İşlemleri için yerel istek karşılamayı etkinleştir codelab'ine benzer alt dizinler ve bulut işlevleri içerir. Ancak app-start
yerine burada app-faulty
var. İşe yarayan bir yerel ev uygulamasıyla başlayacağız.
Firebase'e bağlanma
Akıllı ev işlemleri için yerel istek karşılamayı etkinleştirme codelab'inde oluşturduğunuz projenin aynısını kullanacağız ancak bu codelab'de indirilen dosyaları dağıtacağız.
app-faulty
dizinine gidin, ardından Akıllı ev işlemleri için yerel istek karşılamayı etkinleştir codelab'inde oluşturulan Actions projenizle Firebase CLI'ı ayarlayın:
$ cd app-faulty $ firebase use <project-id>
Firebase'e dağıtma
app-faulty/functions
klasörüne gidin ve npm
kullanarak gerekli tüm bağımlılıkları yükleyin:
$ cd functions $ npm install
Not: Aşağıdaki mesajı görüyorsanız bu mesajı yoksayıp devam edebilirsiniz. Uyarı bazı eski bağımlılıklar nedeniyle gelmiştir. Daha ayrıntılı bilgiyi burada bulabilirsiniz.
found 5 high severity vulnerabilities run `npm audit fix` to fix them, or `npm audit` for details
app-faulty/local/
dizinine gidin ve TypeScript derleyicisini indirip uygulamayı derlemek için aşağıdaki komutları çalıştırın:
$ cd ../local $ npm install $ npm run build
index.ts
(TypeScript) kaynağını derler ve aşağıdaki içerikleri app-faulty/public/local-home/
dizinine yerleştirir:
bundle.js
: Yerel uygulamayı ve bağımlılıkları içeren derlenmiş JavaScript çıkışı.index.html
: Uygulamayı cihaz üzerinde test etmek amacıyla sunmak için kullanılan yerel barındırma sayfası.
Bağımlılıkları yüklediğinize ve projenizi yapılandırdığınıza göre, uygulamayı ilk kez çalıştırmaya hazırsınız.
$ firebase deploy
Aşağıdaki konsol çıkışını görürsünüz:
... ✔ Deploy complete! Project Console: https://console.firebase.google.com/project/<project-id>/overview Hosting URL: https://<projectcd -id>.web.app
Bu komut, birkaç Cloud Functions for Firebase ile birlikte bir web uygulamasını dağıtır.
Home Graph'i güncelleme
Web uygulamasını görüntülemek için tarayıcınızda (https://<project-id>.web.app
) Barındırma URL'sini açın. Web kullanıcı arayüzünde, Senkronizasyon İste seçeneği aracılığıyla HomeGraph'i arızalı yıkama uygulamasındaki en son cihaz meta verileriyle güncellemek için Yenile düğmesini tıklayın:
Google Home uygulamasını aç ve çamaşır makinesinin yeni adının "Hatalı Çamaşır Makinesi" olduğunu doğrula. Cihazı, Nest cihazı bulunan bir odaya atamayı unutmayın.
3. Akıllı çamaşır makinesini çalıştır
Akıllı ev işlemleri için yerel istek karşılamayı etkinleştir codelab'ini çalıştırdıysanız sanal akıllı çamaşır makinesini daha önce başlatmış olmanız gerekir. Durdurulduysa sanal cihazı yeniden başlatmayı unutmayın.
Cihazı başlatma
virtual-device/
dizinine gidin ve yapılandırma parametrelerini bağımsız değişken olarak ileterek cihaz komut dosyasını çalıştırın:
$ cd ../../virtual-device $ npm install $ npm start -- \ --deviceId=deviceid123 --projectId=<project-id> \ --discoveryPortOut=3311 --discoveryPacket=HelloLocalHomeSDK
Cihaz komut dosyasının beklenen parametrelerle çalıştığını doğrulayın:
(...): UDP Server listening on 3311 (...): Device listening on port 3388 (...): Report State successful
4. Yerel Ev Uygulamasını test edin
Google Home cihazına sesli komutlarla cihazınıza aşağıdakiler gibi komutlar gönderin:
"Ok Google, çamaşır makinemi aç."
"Ok Google, çamaşır makinemi çalıştır."
"Ok Google, yerel reklamları zorla."
"Ok Google, çamaşır makinemi durdur."
"Yerel zorla" komutunun ardından çamaşır makinesini kontrol etmeye çalıştığınızda Google Asistan'ın "Maalesef Arızalı Çamaşır Makinesi şu anda kullanılamıyor" şeklinde yanıt verdiğini görürsünüz.
Bu durum, cihaza yerel bir yoldan erişilemediği anlamına gelir. Cihaza yerel bir yoldan erişilemediğinde bulut yolunu kullanmaya başlayacağımız için "Ok Google, zorla yerel" komutu yayınlanmadan önce çalıştı. Ancak "yerel zorla" komutunun ardından bulut yoluna geri dönme seçeneği devre dışı bırakılır.
Sorunun ne olduğunu öğrenmek için sahip olduğumuz araçlardan yararlanalım: Google Cloud Platform (GCP) Metrikler, Günlük Kaydı ve Chrome Geliştirici Araçları.
5. Local Home uygulamasında hata ayıklayın
Aşağıdaki bölümde, cihaza yerel yol üzerinden neden erişilemediğini öğrenmek için Google tarafından sağlanan araçları kullanacaksınız. Google Home cihazına bağlanmak, konsol günlüklerini görüntülemek ve Yerel Ev uygulamasının hatalarını ayıklamak için Google Chrome Geliştirici Araçları'nı kullanabilirsiniz. Ayrıca kullanıcılarınızın Yerel Ev uygulamanızda en sık karşılaştığı hatalardan haberdar olmak için Cloud Logging'e özel günlükler de gönderebilirsiniz.
Chrome Geliştirici Araçları'nı bağlama
Hata ayıklayıcıyı yerel sipariş karşılama uygulamanıza bağlamak için şu adımları uygulayın:
- Google Home cihazınızı, Actions console projesine erişim izni olan bir kullanıcıya bağladığınızdan emin olun.
- Google Home cihazınızı yeniden başlatın. Bu işlem, hem HTML'nizin URL'sini hem de Actions konsoluna yerleştirdiğiniz tarama yapılandırmasını almasını sağlar.
- Geliştirme makinenizde Chrome'u başlatın.
- Yeni bir Chrome sekmesi açın ve denetleyiciyi başlatmak için adres alanına
chrome://inspect
yazın.
Sayfada cihazların bir listesini göreceksiniz. Ayrıca Google Home cihazınızın adının altında uygulama URL'niz görünecektir.
İnceleyiciyi başlatma
Chrome Geliştirici Araçları'nı başlatmak için uygulama URL'nizin altında Denetle'yi tıklayın. Console (Konsol) sekmesini seçin ve TypeScript uygulamanız tarafından yazdırılan IDENTIFY
intent'inin içeriğini görebildiğinizi doğrulayın.
Bu çıkış, IDENTIFY işleyicinin başarıyla tetiklendiği ancak IdentifyResponse
içinde döndürülen verificationId
değerinin HomeGraph'inizdeki hiçbir cihazla eşleşmediği anlamına gelir. Nedenini öğrenmek için birkaç özel günlük ekleyelim.
Özel günlükler ekleyin
Yerel Ev SDK'sı tarafından yazdırılmış bir DEVICE_VERIFICATION_FAILED
hatası olsa da bu hata, sorunun asıl nedenini bulmaya yardımcı olmaz. Tarama verilerini doğru şekilde okuyup işlediğimizden emin olmak için birkaç özel günlük ekleyelim. Sözü bir hata ile reddedersek hata mesajının aslında Cloud Logging'e de gönderileceğini unutmayın.
local/index.ts
identifyHandler(request: IntentFlow.IdentifyRequest):
Promise<IntentFlow.IdentifyResponse> {
console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));
const scanData = request.inputs[0].payload.device.udpScanData;
if (!scanData) {
const err = new IntentFlow.HandlerError(request.requestId,
'invalid_request', 'Invalid scan data');
return Promise.reject(err);
}
// In this codelab, the scan data contains only local device id.
// Is there something wrong here?
const localDeviceId = Buffer.from(scanData.data);
console.log(`IDENTIFY handler: received local device id
${localDeviceId}`);
// Add custom logs
if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
const err = new IntentFlow.HandlerError(request.requestId,
'invalid_device', 'Invalid device id from scan data ' +
localDeviceId);
return Promise.reject(err);
}
const response: IntentFlow.IdentifyResponse = {
intent: Intents.IDENTIFY,
requestId: request.requestId,
payload: {
device: {
id: 'washer',
verificationId: localDeviceId.toString(),
}
}
};
console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));
return Promise.resolve(response);
}
Ayrıca, doğru sürümü kullanıp kullanmadığımızı tanımlayabilmemiz için yerel ana ekran uygulaması sürümünü de değiştirin.
local/index.ts
const localHomeSdk = new App('1.0.1');
Özel günlükleri ekledikten sonra uygulamayı tekrar derlemeniz ve Firebase'e yeniden dağıtmanız gerekir.
$ cd ../app-faulty/local $ npm run build $ firebase deploy --only hosting
Şimdi, güncellenen yerel ana ekran uygulamasını yükleyebilmesi için Google Home cihazınızı yeniden başlatın. Chrome Geliştirici Araçları'ndaki Console günlüklerine bakarak Google Home cihazının beklenen sürümü kullanıp kullanmadığını görebilirsiniz.
Cloud Logging'e erişme
Hatalarınızı bulmak için Cloud Logging'i nasıl kullanacağınıza göz atalım. Projenizde Cloud Logging'e erişmek için:
- Cloud Platform konsolunda Projeler sayfasına gidin.
- Akıllı ev projenizi seçin.
- İşlemler bölümünde, Günlük Kaydı > Günlük Gezgini'ni seçin.
Günlük kaydı verilerine erişim, Actions projenizin kullanıcıları için Identity and Access Management (IAM) üzerinden yönetilir. Günlük kaydı verilerinin rol ve izinleri hakkında daha fazla bilgi için Cloud Logging erişim denetimi başlıklı makaleyi inceleyin.
Gelişmiş filtreleri kullanma
Yerel cihaz tanımlanamadığı için yerel yol çalışmadığından IDENTIFY
amacında hatalar oluştuğunu biliyoruz. Ancak, sorunun tam olarak ne olduğunu bilmek istediğimiz için önce IDENTIFY
işleyicide oluşan hataları filtreleyelim.
Sorgu önizlemesi kutusunu genişletin. kutu, Sorgu oluşturucu kutusuna dönüşür. Sorgu oluşturucu kutusuna jsonPayload.intent="IDENTIFY"
yazın ve Sorgu çalıştır düğmesini tıklayın.
Bunun sonucunda IDENTIFY
işleyiciye gönderilen tüm hata günlüklerini alırsınız. Ardından, son hatayı genişletin. Sözü reddederken ayarladığınız errorCode
ve debugString
değerlerini IDENTIFY
işleyicisinde bulabilirsiniz.
debugString
üzerinden yerel cihaz kimliğinin beklenen biçimde olmadığı anlaşılıyor. Yerel Ev uygulaması, yerel cihaz kimliğini deviceid
ile başlayıp 3 basamaklı bir dize şeklinde almayı bekler. Ancak buradaki yerel cihaz kimliği onaltılık bir dizedir.
Hatayı düzeltme
Tarama verilerinden yerel cihaz kimliğini ayrıştırdığımız kaynak koda döndüğümüzde, dizeyi bayta dönüştürürken kodlamayı sağlamadığımızı fark ederiz. Tarama verileri onaltılık dize olarak alındığından Buffer.from()
çağrılırken karakter kodlaması olarak hex
iletin.
local/index.ts
identifyHandler(request: IntentFlow.IdentifyRequest):
Promise<IntentFlow.IdentifyResponse> {
console.log("IDENTIFY intent: " + JSON.stringify(request, null, 2));
const scanData = request.inputs[0].payload.device.udpScanData;
if (!scanData) {
const err = new IntentFlow.HandlerError(request.requestId,
'invalid_request', 'Invalid scan data');
return Promise.reject(err);
}
// In this codelab, the scan data contains only local device id.
const localDeviceId = Buffer.from(scanData.data, 'hex');
console.log(`IDENTIFY handler: received local device id
${localDeviceId}`);
if (!localDeviceId.toString().match(/^deviceid[0-9]{3}$/gi)) {
const err = new IntentFlow.HandlerError(request.requestId,
'invalid_device', 'Invalid device id from scan data ' +
localDeviceId);
return Promise.reject(err);
}
const response: IntentFlow.IdentifyResponse = {
intent: Intents.IDENTIFY,
requestId: request.requestId,
payload: {
device: {
id: 'washer',
verificationId: localDeviceId.toString(),
}
}
};
console.log("IDENTIFY response: " + JSON.stringify(response, null, 2));
return Promise.resolve(response);
}
Ayrıca, doğru sürümü kullanıp kullanmadığımızı tanımlayabilmemiz için yerel ana ekran uygulaması sürümünü de değiştirin.
local/index.ts
const localHomeSdk = new App('1.0.2');
Hatayı düzelttikten sonra uygulamayı derleyin ve Firebase'e yeniden dağıtın. app-faulty/local
içinde şu komutu çalıştırın:
$ npm run build $ firebase deploy --only hosting
Düzeltmenizi test etme
Dağıtımdan sonra, güncellenmiş yerel ana ekran uygulamasını yükleyebilmesi için Google Home cihazınızı yeniden başlatın. Yerel ana ekran uygulaması sürümünün 1.0.2 olduğundan ve bu sefer Chrome Geliştirici Araçları Konsolu'nda hata görmediğinizden emin olun.
Artık cihazınıza komut göndermeyi tekrar deneyebilirsiniz.
"Ok Google, yerel reklamları zorla."
"Ok Google, çamaşır makinemi durdur."
"Ok Google, çamaşır makinemi aç."
...
"Ok Google, varsayılanı zorla."
6. Akıllı Ev için Test Paketini Çalıştır
Google Home uygulamasındaki dokunma kontrollerini kullanarak veya sesli komutlarla cihazınızı doğruladıktan sonra, kullanım alanlarını İşleminizle ilişkili cihaz türlerine ve özelliklere göre doğrulamak için otomatik Akıllı ev için Test Paketi'nden yararlanabilirsiniz. Test Paketi, İşleminizdeki sorunları tespit etmek için bir dizi test yürütür ve etkinlik günlüklerini derinlemesine incelemeden önce hata ayıklama işleminizi hızlandırmak amacıyla başarısız test durumlarıyla ilgili bilgilendirici mesajlar gösterir.
Akıllı ev için Test Paketi'ni çalıştırın
Akıllı ev İşleminizi Test Suite'e göre test etmek için şu talimatları uygulayın:
- Web tarayıcınızda Akıllı ev için Test Paketi'ni açın.
- Sağ üst köşedeki düğmeyi kullanarak Google'da oturum açın. Bu, Test Paketi'nin komutları doğrudan Google Asistan'a göndermesine olanak tanır.
- Proje Kimliği alanına akıllı ev işleminizin proje kimliğini girin. Ardından, ilerlemek için SONRAKİ'yi tıklayın.
- Test Ayarları adımındaki Cihazlar ve Traisler bölümünde Arızalı Çamaşır Makinesi'ni görmeniz gerekir.
- Örnek yıkama uygulamasında çamaşır makinesi eklemek / çıkarmak / yeniden adlandırmak için kullanıcı arayüzü olmadığından Test İsteği Senkronizasyonu seçeneğini devre dışı bırakın. Üretim sisteminde, kullanıcı cihaz eklediğinde / kaldırdığında / yeniden adlandırdığında Senkronizasyon İste'yi tetiklemeniz gerekir.
- Hem yerel hem de bulut yollarını test edeceğimiz için Local Home SDK (Yerel Ev SDK'sı) seçeneğini etkin bırakın.
- Testi çalıştırmaya başlamak için SONRAKİ'yi tıklayın.
Testler tamamlandığında yerel yoldaki Duraklatma/Devam Ettirme testlerinin başarısız olduğunu ve bulut yolundaki Duraklatma/Devam Ettirme testleri geçemediğini görürsünüz.
Hata mesajını analiz et
Başarısız test durumlarındaki hata mesajlarını daha yakından inceleyin. Size söz konusu testin beklenen ve gerçek durumunun ne olduğunu söyler. Buradaki örnekte, "Çamaşır Makinesini Duraklat" işlemi için beklenen durum isPaused: true
iken gerçek durumda isPaused: false
değerini elde ettik. Benzer şekilde, "Çamaşır Makinesini Duraklat" için beklenen durum isPaused: true
iken gerçek durumda isPaused: false
.
Hata mesajlarından, yerel yolda isPaused
durumunu ters çevirdiğimiz anlaşılıyor.
Hatayı tespit etme ve düzeltme
Local Home uygulamasının, yürütme komutunu cihaza gönderdiği kaynak kodunu bulalım. getDataCommand()
, cihaza gönderilen yürütme komutunda payload
'yi ayarlamak için executeHandler()
tarafından çağrılan işlevdir.
local/index.ts
getDataForCommand(command: string, params: IWasherParams): unknown {
switch (command) {
case 'action.devices.commands.OnOff':
return {
on: params.on ? true : false
};
case 'action.devices.commands.StartStop':
return {
isRunning: params.start ? true : false
};
case 'action.devices.commands.PauseUnpause':
return {
// Is there something wrong here?
isPaused: params.pause ? false : true
};
default:
console.error('Unknown command', command);
return {};
}
}
Gerçekten de isPause
özelliğini ters duruma ayarlıyoruz. params.pause
true
olduğunda true
, aksi takdirde false
olarak ayarlanmalıdır. Gelin bu sorunu çözelim.
local/index.ts
getDataForCommand(command: string, params: IWasherParams): unknown {
switch (command) {
case 'action.devices.commands.OnOff':
return {
on: params.on ? true : false
};
case 'action.devices.commands.StartStop':
return {
isRunning: params.start ? true : false
};
case 'action.devices.commands.PauseUnpause':
return {
isPaused: params.pause ? true : false
};
default:
console.error('Unknown command', command);
return {};
}
}
Doğru sürümü kullanıp kullanmadığımızı belirleyebilmemiz için yerel ana ekran uygulaması sürümünü değiştirin.
local/index.ts
const localHomeSdk = new App('1.0.3');
Uygulamayı tekrar derlemeyi ve Firebase'e yeniden dağıtmayı unutmayın. app-faulty/local
içinde şu komutu çalıştırın:
$ npm run build $ firebase deploy --only hosting
Şimdi, güncellenmiş yerel ana ekran uygulamasını yükleyebilmesi için Google Home cihazınızı yeniden başlatın. Yerel ana ekran uygulaması sürümünün 1.0.3 olduğundan emin olun.
Düzeltmenizi test etme
Şimdi, akıllı ev için test paketini aynı yapılandırmalarla yeniden çalıştırdığınızda tüm test durumlarının geçtiğini göreceksiniz.
7. Tebrikler
Tebrikler! Akıllı ev ve Cloud Logging için Test Paketi aracılığıyla Yerel Ev uygulamasında sorun gidermeyi başarıyla öğrendiniz.
Daha Fazla Bilgi
Şunları da deneyebilirsiniz:
- Cihazınıza daha fazla desteklenen özellik ekleyin ve Test Suite ile test edin.
- Niyet işleyicilerin her birine daha fazla özel günlük ekleyin ve bunları Cloud Logging'de görüntüleyin.
- İşleminizle ilgili faydalı kullanım metrikleri almak için kontrol panelleri oluşturun, uyarılar ayarlayın ve metrik verilerine programatik olarak erişin.
Ayrıca, İşleminizi kullanıcılara yayınlamak için sertifikasyon süreci de dahil olmak üzere bir İşlemi test etme ve incelemeye gönderme hakkında daha fazla bilgi edinebilirsiniz.