Yerel Evde Hata Ayıklama

1. Başlamadan önce

Akıllı ev entegrasyonları, Google Asistan'ın kullanıcıların evlerindeki bağlı cihazları kontrol etmesini sağlar. Akıllı ev İşlemi derlemek için akıllı ev niyetlerini işleyebilecek bir bulut 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 komutu bulut karşılamanıza gönderir.

Yerel Ev SDK'sı, akıllı ev intent'lerini doğrudan bir Google Home cihazına yönlendirmek için yerel bir yol ekleyerek akıllı ev entegrasyonunuzu iyileştirir. Bu da güvenilirliği artırır ve kullanıcıların komutlarını işlemede gecikmeyi azaltır. TypeScript veya JavaScript ile cihazları tanımlayan ve herhangi bir Google Home akıllı hoparlöründe ya da Google Nest akıllı ekranında komut yürüten bir yerel sipariş karşılama uygulaması yazmanıza ve dağıtmanıza olanak tanır. Ardından uygulamanız, komutları yerine getirmek için mevcut standart protokolleri kullanarak yerel alan ağı üzerinden kullanıcıların mevcut akıllı cihazlarıyla doğrudan iletişim kurar.

Akıllı ev Actions'da hata ayıklama, Actions'ınızı üretim kalitesiyle derlemek için kritik bir adımdır. Bununla birlikte, bilgilendirici ve kullanımı kolay sorun giderme ve test araçları olmaksızın hem zaman alıcı hem de zorlu bir süreçtir. Akıllı ev Actions hata ayıklamasını kolaylaştırmak için Google Cloud Platform (GCP) Metrikleri ile Günlük Kaydı'nı ve Akıllı ev için Test Paketi'ni kullanarak Action'larınızla ilgili sorunları tespit edip çözebilirsiniz.

Ön koşullar

• Akıllı ev işlemi oluşturma geliştirici kılavuzu
• Akıllı ev işlemleri için yerel karşılamayı etkinleştir codelab'ini çalıştırın

Derlemeniz istenen nedir?

Bu codelab'de, akıllı ev İşlemleri için yerel bir karşılama 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ında hata ayıklaması yapacaksınız.

Neler öğreneceksiniz?

• Üretim sorunlarını tanımlamak ve çözmek için GCP Metrikleri ve Günlük Kaydı'nı kullanma.
• İşlevsel ve API sorunlarını belirlemek 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ı olan bir iOS veya Android cihaz
• Google Home akıllı hoparlör veya Google Nest akıllı ekran
• Node.js sürüm 10.16 veya üstü
• Bir Google Hesabı
• Google Cloud faturalandırma hesabı

2. Çamaşır makinesi uygulamasını çalıştır

Kaynak kodunu alma

Bu codelab'in örneğini geliştirme makinenize indirmek için aşağıdaki bağlantıyı tıklayın:

file_downloadKaynak kodunu indirin

...veya GitHub deposunu komut satırından klonlayabilirsiniz:

$ git clone https://github.com/googlecodelabs/smarthome-debug-local.git

Proje hakkında

Başlangıç uygulaması, akıllı ev İşlemleri için yerel karşılamayı etkinleştir codelab'ine benzer alt dizinler ve bulut işlevleri içerir. Burada app-start yerine app-faulty var. İşe yarayan, ancak o kadar iyi sonuç vermeyen yerel bir ev uygulamasıyla başlıyoruz.

Firebase'e bağlanma

Akıllı ev Actions için yerel karşılamayı etkinleştir codelab'de oluşturduğunuz projeyi kullanacağız ancak bu codelab'de indirilen dosyaları dağıtacağız.

app-faulty dizinine gidin, ardından Akıllı ev İşlemleri için yerel karşılamayı etkinleştir codelab'de oluşturulan Actions projenizle Firebase CLI'yı 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ürseniz yoksayıp devam edebilirsiniz. Uyarı, daha eski bazı bağımlılardan kaynaklanmaktadır ve daha fazla bilgiye buradan ulaşabilirsiniz.

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

Bu, 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 derlenen JavaScript çıkışı.
• index.html - Uygulamayı cihazda test etmek için kullanılan yerel barındırma sayfası.

Bağımlılıkları yükleyip projenizi yapılandırdığınıza göre uygulamayı ilk kez çalıştırmaya hazırsınız.

$ firebase deploy

Görmeniz gereken konsol çıkışı şudur:

...

✔ Deploy complete!

Project Console: https://console.firebase.google.com/project/<project-id>/overview
Hosting URL: https://<projectcd -id>.web.app

Bu komut, bir uygulamayı birkaç Firebase için Cloud Functions ile birlikte dağıtır.

HomeGraph'i güncelleme

Web uygulamasını görüntülemek için tarayıcınızda https://<project-id>.web.app Hosting URL'yi açın. Web kullanıcı arayüzünde Refresh (Yenile) düğmesini tıklayarak HomeGraph'i, hatalı çamaşır makinesi uygulamasından en son cihaz meta verileriyle Sync Sync aracılığıyla güncelleyin:

Google Home uygulamasını açıp çamaşır makinesi cihazını yeni bir adla "Hatalı çamaşır makinesi" olarak görebildiğinizi doğrulayın. Cihazı, içinde Nest cihazı olan bir odaya atamayı unutmayın.

3. Akıllı çamaşır makinesini çalıştır

Akıllı ev işlemleri için yerel karşılamayı etkinleştir codelab'ini çalıştırdıysanız sanal akıllı çamaşır makinesini zaten başlatmış olmanız gerekir. Durdurulduysa sanal cihazı yeniden başlatmayı unutmayın.

Cihazı başlatın

virtual-device/ dizinine gidin ve yapılandırma parametrelerini bağımsız değişkenler 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 etme

Komutları cihazınıza Google Home cihazına sesli komutlar göndererek gönderin. Örneğin:

"Ok Google, çamaşır makinemi aç."

"Ok Google, çamaşır makinemi başlat."

"Ok Google, yereli zorla."

"Ok Google, çamaşır makinemi durdur."

Çamaşır makinesini "yerel ayarı zorunlu kıl" ayarından sonra kontrol etmeye çalıştığınızda Google Asistan'ın, "Hatalı çamaşır makinesi şu anda kullanılamıyor gibi görünüyor" mesajıyla yanıt verdiğini fark edeceksiniz.

Bu, cihaza yerel bir yol üzerinden ulaşılamayacağı anlamına gelir. "Ok Google, yereli zorunlu kıl" seçeneği sunulmadan önce çalıştı. Çünkü cihaza yerel bir yol üzerinden erişilemediğinde bulut yolunu kullanmaya devam edeceğiz. Ancak, "yerel ayarı zorunlu kıl" seçeneğinden sonra, bulut yoluna geri dönme seçeneği devre dışı bırakılır.

Sorunun ne olduğunu anlamak için şu araçlarımızdan yararlanalım: Google Cloud Platform (GCP) Metrikler ve Günlük Kaydı ve Chrome Geliştirici Araçları.

5. Yerel Ev uygulamasında hata ayıklama

Sonraki 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ında hata ayıklamak için Google Chrome Geliştirici Araçları'nı kullanabilirsiniz. Ayrıca, Cloud Logging'e özel günlükler göndererek kullanıcılarınızın Yerel Home uygulamanızda en sık karşılaştığı hataları görebilirsiniz.

Chrome Geliştirici Araçları'nı bağlama

Hata ayıklayıcıyı yerel sipariş karşılama uygulamanıza bağlamak için aşağıdaki adımları uygulayın:

1. Google Home cihazınızı, Actions Console projesine erişim izni olan bir kullanıcıya bağladığınızdan emin olun.
2. Google Home cihazınızı yeniden başlatın. Böylece Google Console'a yerleştirdiğiniz tarama yapılandırmasının yanı sıra HTML'nizin URL'sini de alabilir.
3. Chrome'u geliştirme makinenizde başlatın.
4. İnceleyiciyi başlatmak için yeni bir Chrome sekmesi açın ve adres alanına chrome://inspect yazın.

Sayfada cihazların listesi görünür ve uygulama URL'niz, Google Home cihazınızın adının altında görünür.

İnceleyiciyi başlatma

Chrome Geliştirici Araçları'nı başlatmak için uygulama URL'nizin altında İncele'yi tıklayın. Console (Konsol) sekmesini seçin ve IDENTIFY intent'in (TypeScript uygulamanız tarafından yazdırılan) içeriğini görebileceğinizi doğrulayın.

Bu çıkış, IDENTIFY işleyicisinin başarıyla tetiklendiği anlamına gelir ancak IdentifyResponse içinde döndürülen verificationId, HomeGraph cihazınızdaki hiçbir cihazla eşleşmiyor. Bunun nedenini öğrenmek için birkaç özel günlük ekleyelim.

Özel günlük ekle

Yerel Ev SDK'sı tarafından yazdırılan bir DEVICE_VERIFICATION_FAILED hatası olsa da temel nedenin bulunmasına çok fazla yardımcı olmaz. Tarama verilerini doğru okuduğumuzdan ve işlediğimizden emin olmak için bazı özel günlükler ekleyelim ve bir vaadin hatalı olması durumunda 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ı belirleyebilmemiz için yerel ev uygulaması sürümünü 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üncellenmiş yerel ev 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şin

Hatalarınızı bulmak için Cloud Logging'i nasıl kullanabileceğinize göz atalım. Projenizde Cloud Logging'e erişmek için:

1. Cloud Platform Console'da Projeler sayfasına gidin.
2. Akıllı ev projenizi seçin.
3. İşlemler altında, 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 Kimlik ve Erişim Yönetimi (IAM) üzerinden yönetilir. Veri günlük kaydı rolleri ve izinleri hakkında daha fazla bilgi için Cloud Logging erişim denetimi başlıklı makaleye bakın.

Gelişmiş filtreleri kullanma

Yerel cihaz tanımlanamadığı için yerel yol çalışmadığından IDENTIFY hatasıyla ilgili hatalar oluştuğunu biliyoruz. Ancak sorunun tam olarak ne olduğunu öğrenmek istiyoruz. Bu nedenle öncelikle IDENTIFY işleyicisinde oluşan hataları filtreleyin.

Sorgu önizleme kutusunu genişletin. Bu kutu Sorgu oluşturucu kutusuna dönüşür. Sorgu oluşturucu kutusuna jsonPayload.intent="IDENTIFY" yazıp Sorgu çalıştır düğmesini tıklayın.

Sonuç olarak, IDENTIFY işleyicisine gönderilen tüm hata günlükleri alırsınız. Ardından, son hatayı genişletin. Taahhüdü reddederken az önce ayarladığınız errorCode ve debugString öğelerini IDENTIFY işleyicide bulabilirsiniz.

debugString içinden yerel cihaz kimliğinin beklenen biçimde olmadığını anlayabiliriz. Yerel Ev uygulaması, yerel cihaz kimliğini deviceid ile başlayıp 3 basamaklı bir dize olarak almayı bekler, ancak buradaki yerel cihaz kimliği on altılık bir dizedir.

Hatayı düzeltin

Yerel cihaz kimliğini tarama verilerinden ayrıştırdığımız kaynak koduna dönersek, dizeyi baytlara dönüştürürken kodlama sağlamadığımızı fark ederiz. Tarama verileri on altılı dize olarak alınır. Dolayısıyla, Buffer.from() çağırırken karakter kodlaması olarak hex değerini 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ı belirleyebilmemiz için yerel ev uygulaması sürümünü değiştirin.

local/index.ts

const localHomeSdk = new App('1.0.2');

Hatayı düzelttikten sonra uygulamayı derleyip Firebase'e yeniden dağıtın. app-faulty/local uygulamasında şunu çalıştırın:

$ npm run build
$ firebase deploy --only hosting

Düzeltmenizi test etme

Dağıtımdan sonra, Google Home cihazınızın güncellenmiş yerel ev uygulamasını yükleyebilmesi için yeniden başlatın. Yerel ev uygulaması sürümünün 1.0.2 olduğundan emin olun ve bu kez Chrome Geliştirici Araçları Konsolu'nda hiçbir hata olmamasını sağlayın.

Şimdi cihazınıza tekrar komut göndermeyi deneyebilirsiniz.

"Ok Google, yereli zorla."

"Ok Google, çamaşır makinemi durdur."

"Ok Google, çamaşır makinemi aç."

...

"Ok Google, varsayılanı zorunlu tut."

6. Akıllı Ev için Test Paketi Çalıştır

Google Home uygulamasındaki dokunma kontrollerini kullanarak veya sesli komutlarla cihazınızı doğruladıktan sonra, Action'ınızla ilişkili cihaz türlerine ve özelliklere göre kullanım alanlarını doğrulamak için otomatik olarak sunulan Akıllı Ev için Test Paketi'ni kullanabilirsiniz. Test Paketi, İşleminizdeki sorunları tespit etmek için bir dizi test yapar ve olay günlüklerine girmeden önce hata ayıklama sürecini hızlandırmak amacıyla başarısız test durumları için bilgilendirici mesajlar gösterir.

Akıllı ev için Test Paketi çalıştır

Test evinizdeki akıllı ev Action'ınızı test etmek için şu talimatları uygulayın:

1. Web tarayıcınızda Akıllı ev için test paketini açın.
2. Sağ üst köşedeki düğmeyi kullanarak Google'da oturum açın. Bu sayede Test Paketi, komutları doğrudan Google Asistan'a gönderebilir.
3. Proje Kimliği alanına, akıllı ev Action'ınızın proje kimliğini girin. Ardından devam etmek için İLERİ'yi tıklayın.
4. Test Ayarları adımında, Hatalı Çamaşır Makinenizi Cihazlar ve Trafiğe bölümünde görürsünüz.
5. Örnek çamaşır makinesi uygulamasının çamaşır makinesinin eklenmesi/kaldırılması/yeniden adlandırılması için bir kullanıcı arayüzü olmadığından İsteği Senkronizasyonunu Test Et seçeneğini devre dışı bırakın. Bir üretim sisteminde, kullanıcı cihaz eklediğinde/kaldırdığında/yeniden adlandırdığında Senkronizasyon İste ayarını tetiklemeniz gerekir.
6. Hem yerel yolları hem de bulut yollarını test edeceğimizden Yerel Ev SDK'sı seçeneğini etkin bırakın.
7. Testi çalıştırmaya başlamak için SONRAKİ'yi tıklayın.

Testler tamamlandığında, bulut yolundaki Duraklat/Devam Ettirme testleri başarılı olurken, yerel yoldaki Duraklatma/Devam Ettirme testlerinin başarısız olduğunu fark edersiniz.

Hata mesajını analiz et

Başarısız test durumlarında hata mesajlarını daha yakından inceleyin. Size bu testin beklenen durumunu ve gerçek durumunu söylerler. Bu durumda, "Çamaşır makinesini duraklat" için beklenen durum isPaused: true, ancak gerçek durumda isPaused: false sonucunu aldık. Benzer şekilde, "Çamaşır makinesini duraklat" için beklenen durum isPaused: true, ancak gerçek durumda isPaused: false değerini aldık.

Hata mesajlarında, yerel yolda isPaused durumunu ters çeviriyoruz.

Hatayı tanımlayın ve düzeltin

Yerel Home uygulamasının yürütme komutunu cihaza gönderdiği kaynak kodu bulalım. getDataCommand(), cihaza gönderilen yürütme komutunda payload değerini 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 {};
    }
}

isPause ayarlarını ters yönde ayarlıyoruz. params.pause true ise aksi takdirde true olarak ayarlanmalıdır. Şimdi 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 ev 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 uygulamasında şunu çalıştırın:

$ npm run build
$ firebase deploy --only hosting

Şimdi, güncellenmiş yerel ev uygulamasını yükleyebilmesi için Google Home cihazınızı yeniden başlatın. Yerel ev 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ırın, tüm test durumlarının başarılı olduğunu göreceksiniz.

7. Tebrikler

Tebrikler. Akıllı Ev ve Cloud Logging Test Testi aracılığıyla Yerel Ev uygulamasıyla ilgili sorunları nasıl gidereceğinizi başarıyla öğrendiniz.

Daha Fazla Bilgi

Şunları da deneyebilirsiniz:

• Cihazınıza daha fazla desteklenen özellik ekleyin ve Test Paketi ile test yapın.
• Amaç işleyicilerinin her birine daha fazla özel günlük ekleyin ve bunları Cloud Logging'de görüntüleyin.
• İşleminizle ilgili faydalı kullanım metriklerine ulaşmak için gösterge tabloları oluşturun, uyarılar oluşturun ve metriklere programatik olarak erişin.

Ayrıca, İşleminizi kullanıcılara yayınlamak için onay süreci de dahil olmak üzere, bir İşlemi inceleme için test etme ve gönderme hakkında daha fazla bilgi edinebilirsiniz.