Yerel Evin Hata Ayıklaması

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 işlemi oluşturmak için akıllı ev intent'lerini 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 buluttan tamamlama hizmetinize gönderir.

Yerel Ev SDK'sı, akıllı ev amaçlarını doğrudan bir Google Home cihazına yönlendirecek yerel bir yol ekleyerek akıllı ev entegrasyonunuzu iyileştirir. Bu sayede güvenilirliği artırır ve kullanıcı komutlarının işlenmesinde gecikmeyi azaltabilirsiniz. TypeScript veya JavaScript'te, cihazları tanımlayan ve herhangi bir Google Home akıllı hoparlörde ya da Google Nest akıllı ekranda komutları yürüten yerel bir uygulama 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 İşlemleri'nde hata ayıklama, İşlemlerinizi üretim kalitesinde oluşturmak için kritik bir adımdır. Ancak bilgilendirici ve kullanımı kolay sorun giderme ve test araçları olmadan bu işlem zor ve zaman alıcıdır. Akıllı ev Actions'larında hata ayıklamayı kolaylaştırmak için Google Cloud Platform (GCP) Metrikler ve Günlük'e ve Akıllı ev için Test Paketi'ne erişebilirsiniz. Bu araçlar, Actions'larınızdaki sorunları tespit etmenize ve çözmenize yardımcı olur.

Ön koşullar

• Akıllı ev için İşlem oluşturma geliştirici kılavuzu
• Akıllı ev işlemleri için yerel karşılama özelliğini etkinleştirme codelab'ini çalıştırın.

Ne oluşturacaksınız?

Bu codelab'de, akıllı ev İşlemleri için yerel bir karşılama oluşturacak ve bunu 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ıklama yapacaksınız.

Neler öğreneceksiniz?

• Üretim sorunlarını tespit edip çözmek için GCP metriklerini ve günlük kaydını kullanma.
• İşlevsel ve API sorunlarını tespit etmek için Test Paketi'ni kullanma
• Yerel Home uygulamanızı geliştirirken Chrome Geliştirici Araçları'nı kullanma.

İhtiyacınız olanlar

• 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 bir sürüm
• Bir Google Hesabı
• Google Cloud faturalandırma hesabı

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

Kaynak kodunu alma

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

file_downloadKaynak kodu indir

İsterseniz GitHub deposunu komut satırından klonlayabilirsiniz:

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

Proje hakkında

Başlatıcı uygulama, Akıllı ev işlemleri için yerel karşılama özelliğini etkinleştirme kod laboratuvarındakiyle benzer alt dizinleri ve bulut işlevlerini içerir. Ancak burada app-start yerine app-faulty var. Çalışan ancak çok iyi çalışmayan yerel bir ev uygulamasıyla başlayacağız.

Firebase'e bağlanma

Akıllı ev İşlemleri için yerel yerine getirmeyi etkinleştirme kod laboratuvarında oluşturduğunuz projeyi kullanacağız ancak bu kod laboratuvarında indirilen dosyaları dağıtacağız.

app-faulty dizinine gidin, ardından Akıllı ev İşlemleri için yerel karşılama özelliğini etkinleştirme kod laboratuvarında oluşturduğunuz İşlemler projenizle Firebase CLI'yi ayarlayın:

$ cd app-faulty
$ firebase use <project-id>

Firebase'e dağıtma

app-faulty/functions klasörüne gidin ve npm'u 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. Bu uyarı, bazı eski bağımlılıklardan kaynaklanmaktadır. Daha fazla bilgiyi burada bulabilirsiniz.

found 5 high severity vulnerabilities
  run `npm audit fix` to fix them, or `npm audit` for details

TypeScript derleyicisini indirip uygulamayı derlemek için app-faulty/local/ dizine gidin ve aşağıdaki komutları çalıştırın:

$ cd ../local
$ npm install
$ npm run build

Bu işlem, 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 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

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, çeşitli Firebase için Cloud Functions işleviyle birlikte bir web uygulaması dağıtır.

HomeGraph'ı 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 iste aracılığıyla HomeGraph'ı hatalı çamaşır makinesi uygulamasındaki en son cihaz meta verileriyle güncellemek için Yenile düğmesini tıklayın:

Google Home uygulamasını açıp çamaşır makinenizi "Arızalı Çamaşır Makinesi" adlı yeni bir adla görebildiğinizi doğrulayın. Cihazı, içinde 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 sipariş karşılamayı etkinleştir codelab'ini çalıştırdıysanız sanal akıllı çamaşır makinesini daha önce başlatmış olmanız gerekir. Çalışma 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 Home uygulamasını test etme

Google Home cihaza sesli komut vererek cihazınıza komut gönderebilirsiniz. Örneğin:

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

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

"Ok Google, yerele zorla."

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

"Yerel olarak zorla" seçeneğini belirledikten sonra çamaşır makinesini kontrol etmeye çalıştığınızda Google Asistan'ın "Maalesef Arızalı Çamaşır Makinesi şu anda kullanılamıyor" yanıtını verdiğini görürsünüz.

Bu, cihaza yerel bir yolla erişilemediği anlamına gelir. Cihaz yerel bir yol üzerinden erişilemez olduğunda bulut yolunu kullanmaya geri döneceğimiz için "Hey Google, yereli zorla" komutu verilmeden önce çalışıyordu. Ancak "yerel olarak zorla" seçeneğinden sonra bulut yoluna geri dönme seçeneği devre dışı bırakılır.

Sorunun ne olduğunu öğrenmek için elimizdeki araçları kullanalım: Google Cloud Platform (GCP) Metrikler ve Günlük ile Chrome Geliştirici Araçları.

5. Yerel Home uygulamasında hata ayıklama

Aşağıdaki bölümde, cihaza yerel yol üzerinden neden ulaşılamadığını öğ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 Home uygulamasında hata ayıklama yapmak için Google Chrome Geliştirici Araçları'nı kullanabilirsiniz. Ayrıca, kullanıcılarınızın yerel Home uygulamanızda bulduğu en yaygın hataları öğrenebilmek için Cloud Logging'a özel günlükler gönderebilirsiniz.

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

Hata ayıklayıcıyı yerel sipariş tamamlama 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. Bu şekilde, HTML'nizin URL'sinin yanı sıra Actions konsoluna yerleştirdiğiniz tarama yapılandırmasını da alır.
3. Geliştirme makinenizde Chrome'u başlatın.
4. Yeni bir Chrome sekmesi açın ve adres alanına chrome://inspect yazarak denetleyiciyi başlatın.

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

Denetleyiciyi başlatma

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

Bu çıkış, IDENTIFY işleyicisinin başarıyla tetiklendiği ancak IdentifyResponse içinde döndürülen verificationId değerinin HomeGraph'ınızdaki cihazlardan hiçbiriyle eşleşmediği anlamına gelir. Bunun nedenini öğrenmek için bazı özel günlükler ekleyelim.

Özel günlükler ekleme

Yerel Ev SDK'sı tarafından yazdırılan bir DEVICE_VERIFICATION_FAILED hatası olsa da bu hata, sorunun temel nedenini bulmaya pek yardımcı olmaz. Tarama verilerini doğru şekilde okuyup işlediğimizden emin olmak için bazı özel günlükler ekleyelim. Sözleşmeyi bir hatayla reddedersek hata mesajının aslında Cloud Logging'a da gönderildiğ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ığınızı belirleyebilmemiz için yerel ana ekran 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

Ardından, güncellenmiş yerel ana sayfa uygulamasını yükleyebilmesi için Google Home cihazınızı yeniden başlatın. Google Home cihazının beklenen sürümü kullanıp kullanmadığını Chrome Geliştirici Araçları'ndaki Konsol günlüklerine bakarak 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. Projeniz için Cloud Logging'a erişmek üzere:

1. Cloud Platform Console'da Projeler sayfasına gidin.
2. Akıllı ev projenizi seçin.
3. İşlemler bölümünde Günlük Kaydı > Günlük Gezgini'ni seçin.

Günlük verilerine erişim, Actions projenizin kullanıcıları için Kimlik ve Erişim Yönetimi (IAM) aracılığıyla yönetilir. Verileri günlük kaydetmeyle ilgili roller ve izinler 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ığından yerel yol çalışmadığından IDENTIFY amacında hatalar ortaya çıktığını biliyoruz. Ancak sorunun tam olarak ne olduğunu öğrenmek istiyoruz. Bu nedenle, önce IDENTIFY işleyicisinde gerçekleşen hataları filtreleyelim.

Sorguyu göster açma/kapatma düğmesini tıklayın. Bu, Sorgu oluşturucu kutusuna dönüşür. Sorgu oluşturucu kutusuna jsonPayload.intent="IDENTIFY" yazın ve Sorguyu çalıştır düğmesini tıklayın.

Sonuç olarak, IDENTIFY işleyicisinde oluşturulan tüm hata günlüklerini alırsınız. Ardından, son hatayı genişletin. Sözleşmeyi reddederseniz ayarladığınız errorCode ve debugString değerlerini IDENTIFY işleyicisinde bulabilirsiniz.

debugString dosyasından, yerel cihaz kimliğinin beklenen biçimde olmadığını anlayabiliriz. Yerel Home uygulaması, yerel cihaz kimliğini deviceid ile başlayan ve ardından 3 basamak gelen bir dize olarak 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 geri döndüğümüzde, dize baytlara dönüştürülürken kodlamayı sağlamadığımızı fark ediyoruz. Tarama verileri on altılık dize olarak alınır. Bu nedenle, Buffer.from() işlevini ç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ığınızı belirleyebilmemiz için yerel ana ekran uygulaması sürümünü 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'te şunları çalıştırın:

$ npm run build
$ firebase deploy --only hosting

Düzeltme işleminizi test etme

Dağıtım işleminden sonra, 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.2 olduğundan emin olun. Bu kez Chrome Geliştirici Araçları Konsolu'nda hata görmezsiniz.

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

"Ok Google, yerele zorla."

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

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

...

"Ok Google, varsayılan ayarı zorla."

6. Akıllı Ev için Test Paketi'ni çalıştırma

Google Home uygulamasındaki dokunmatik kontrolleri veya sesli komutları kullanarak cihazınızı doğruladıktan sonra, işleminizle ilişkili cihaz türlerine ve özelliklere göre kullanım alanlarını doğrulamak için otomatik Akıllı Ev Test Paketi'ni kullanabilirsiniz. Test paketi, işleminizdeki sorunları tespit etmek için bir dizi test çalıştırır ve etkinlik günlüklerine göz atmadan önce hata ayıklamanızı hızlandırmak için başarısız test durumlarıyla ilgili bilgilendirici mesajlar gösterir.

Akıllı ev için Test Paketi'ni çalıştırma

Akıllı ev Action by Test Suite'i test etmek için şu talimatları uygulayın:

1. Web tarayıcınızda Akıllı ev için Test Paketi'ni 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 işleminizin proje kimliğini girin. Ardından, devam etmek için SONRAKİ'yi tıklayın.
4. Test Ayarları adımında, Cihazlar ve Cihazlar bölümünde Hatalı Çamaşır Makinenizi göreceksiniz.
5. Örnek çamaşır makinesi uygulamasında çamaşır makinesinin eklenmesi, kaldırılması veya yeniden adlandırılması için kullanıcı arayüzü olmadığından Senkronizasyon İsteğini Test Et seçeneğini devre dışı bırakın. Üretim sisteminde, kullanıcı cihaz eklediğinde/kaldırdığında/adını değiştirdiğinde Senkronizasyon İste'yi tetiklemeniz gerekir.
6. Hem yerel hem de bulut yollarını test edeceğimizden Yerel Ev SDK'sı seçeneğini etkin durumda bırakın.
7. Testi çalıştırmaya başlamak için Sonraki: Test ortamı'nı tıklayın.

Testler tamamlandığında, bulut yolundaki Duraklat/Devam Ettir testleri geçerken yerel yoldaki Duraklat/Devam ettir testlerinin başarısız olduğunu görürsünüz.

Hata mesajını analiz et

Başarısız test durumlarındaki hata mesajlarına daha yakından bakın. Bu test için beklenen durumun ne olduğunu ve gerçek durumun ne olduğunu size bildirir. Bu durumda, "Yıkayıcıyı duraklat" için beklenen durum isPaused: true iken gerçek durum isPaused: false olarak döndürülmüştür. Benzer şekilde, "Yıkayıcıyı duraklat" için beklenen durum isPaused: true iken gerçek durum isPaused: false.

Hata mesajlarından anlaşıldığı kadarıyla isPaused durumunu yerel yoldan ters şekilde ayarlıyoruz.

Hatayı tespit edip düzeltme

Yerel Home uygulamasının cihaza yürütme komutunu gönderdiği kaynak kodunu 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'ü ters durumda ayarlıyoruz. params.pause true olduğunda isPause true, aksi takdirde false olarak ayarlanmalıdır. Şimdi bunu düzeltelim.

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 Home 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

Ardından, güncellenmiş yerel Home uygulamasını yükleyebilmesi için Google Home cihazınızı yeniden başlatın. Yerel Home uygulamasının sürümünün 1.0.3 olduğundan emin olun.

Düzeltme işleminizi 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 geçtiğini göreceksiniz.

7. Tebrikler

Tebrikler! Akıllı ev için Test Paketi ve Cloud Günlük Kaydı'nı kullanarak yerel Home uygulamasında nasıl sorun gidereceğinizi öğrendiniz.

Daha Fazla Bilgi

Deneyebileceğiniz bazı ek yöntemler:

• Cihazınıza daha fazla desteklenen özellik ekleyin ve Test Paketi ile test edin.
• Intent işleyicilerinin her birine daha fazla özel günlük ekleyin ve bunları Cloud Logging'da görüntüleyin.
• İşleminiz hakkında faydalı kullanım metrikleri elde etmek için gösterge tabloları oluşturun, uyarılar ayarlayın ve metrik verilerine programatik olarak erişin.

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