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. Buluttan buluta entegrasyon oluşturmak için akıllı ev intent'lerini işleyebilen 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şılama işlevinize gönderir.

Yerel Ev SDK'sı, akıllı ev intent'lerini doğrudan bir Google Home cihazına yönlendirecek yerel bir yol ekleyerek akıllı ev entegrasyonunuzu geliştirir. Bu sayede, kullanıcı komutlarının işlenmesinde güvenilirlik artar ve gecikme süresi azalır. Bu araç, cihazları tanımlayan ve herhangi bir Google Home akıllı hoparlör veya Google Nest akıllı ekranda komutları yürüten bir yerel karşılama uygulamasını TypeScript veya JavaScript ile yazıp dağıtmanıza olanak tanır. Uygulamanız daha sonra 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.

Buluttan buluta entegrasyonlarda hata ayıklama, entegrasyonlarınızı ü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 zorlu ve zaman alıcıdır. Buluttan buluta entegrasyonlarında hata ayıklamayı kolaylaştırmak için Google Cloud Platform (GCP) Metrikleri, Günlük Kaydı ve Akıllı Ev için Test Paketi, entegrasyonlarınızdaki sorunları belirlemenize ve çözmenize yardımcı olmak üzere kullanılabilir.

Ön koşullar

• Buluttan buluta entegrasyon oluşturma geliştirici kılavuzu
• Buluttan buluta entegrasyonlar için yerel karşılama özelliğini etkinleştirme adlı codelab'i çalıştırın.

Ne oluşturacaksınız?

Bu codelab'de, buluttan buluta entegrasyonlar için yerel bir intent 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 ile Google Home uygulamasında hata ayıklayacaksınız.

Neler öğreneceksiniz?

• Üretim sorunlarını belirlemek 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

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

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

Kaynak kodu alma

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

file_downloadKaynak kodu indir

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

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

Proje hakkında

Başlangıç uygulaması, Buluttan buluta entegrasyonları için yerel karşılama özelliğini etkinleştirme adlı codelab'deki alt dizinlere ve Cloud Functions işlevlerine benzer. Ancak burada app-start yerine app-faulty var. İşe, iyi çalışmayan ancak işe yarayan yerel bir ev uygulamasıyla başlayacağız.

Firebase'e bağlanma

Buluttan buluta entegrasyonlar için yerel karşılama özelliğini etkinleştirme adlı codelab'de oluşturduğunuz projeyi kullanacağız ancak bu codelab'de indirilen dosyaları dağıtacağız.

app-faulty dizinine gidin, ardından Enable local fulfillment for Cloud-to-cloud integrations (Buluttan buluta entegrasyonlar için yerel karşılama özelliğini etkinleştirme) codelab'inde oluşturduğunuz entegrasyon 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 yoksayabilir ve devam edebilirsiniz. Uyarı, eski bağımlılıklardan kaynaklanmaktadır. Daha fazla ayrıntıyı 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

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 için sunmak üzere 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 web uygulamasının yanı sıra çeşitli Cloud Functions for Firebase işlevlerini dağıtır.

HomeGraph'ı güncelleme

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

Google Home uygulamasını açın ve çamaşır makinenizin "Arızalı Çamaşır Makinesi" adıyla göründüğünü doğrulayın. Cihazı, içinde Nest cihazı bulunan bir odaya atamayı unutmayın.

3. Akıllı çamaşır makinesini başlatma

Enable local fulfillment for Cloud-to-cloud integrations (Buluttan buluta entegrasyonlarda yerel karşılama özelliğini etkinleştirme) adlı codelab'i çalıştırdıysanız sanal akıllı çamaşır makinesini başlatmış olmanız gerekir. Durdurulmuşsa 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ş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 Etme

Google Home cihazına sesli komutlar vererek cihazınıza komut gönderme (ör. aşağıdaki komutlar):

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

"Ok Google, çamaşır makinem çalışsın."

"Ok Google, yerel olarak zorla."

"Ok Google, çamaşır makinem durdurulsun."

"Force local" komutundan sonra çamaşır makinesini kontrol etmeye çalıştığınızda Google Asistan'ın "Üzgünüm, arızalı çamaşır makinesi şu anda kullanılamıyor" şeklinde yanıt verdiğini görürsünüz.

Bu, cihaza yerel bir yoldan erişilemediği anlamına gelir. Cihaza yerel yoldan erişilemediğinde bulut yolu kullanılacağından, "Ok Google, yerel olarak zorla" komutu verilmeden önce çalışıyordu. Ancak "yerel zorlama" işleminden sonra bulut yoluna geri dönme seçeneği devre dışı bırakılır.

Sorunun ne olduğunu öğrenmek için Google Cloud Platform (GCP) Metrics ve Logging ile Chrome Geliştirici Araçları'nı kullanalım.

5. Yerel Home uygulamasında hata ayıklama

Aşağıdaki bölümde, cihazın yerel yol üzerinden neden erişilebilir olmadığı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 Ev uygulamasında hata ayıklamak için Google Chrome Geliştirici Araçları'nı kullanabilirsiniz. Ayrıca, kullanıcılarınızın Yerel Ev uygulamanızda karşılaştığı en önemli 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 karşılama uygulamanıza bağlamak için aşağıdaki adımları uygulayın:

1. Google Home cihazınızı Play 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 cihaz, HTML'nizin URL'sini ve Developer Console'da girdiğiniz tarama yapılandırmasını alabilir.
3. Geliştirme makinenizde Chrome'u başlatın.
4. Yeni bir Chrome sekmesi açın ve inceleyiciyi başlatmak için adres alanına chrome://inspect girin.

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. Console (Konsol) sekmesini seçin ve TypeScript uygulamanız tarafından yazdırılan IDENTIFY amacının 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 Home Graph'ınızdaki cihazlardan herhangi biriyle eşleşmediği anlamına gelir. Nedenini öğrenmek için bazı özel günlükler ekleyelim.

Özel günlükler ekleme

Local Home SDK tarafından yazdırılan bir DEVICE_VERIFICATION_FAILED hatası olsa da bu hata, kök nedeni bulmaya pek yardımcı olmaz. Tarama verilerini doğru şekilde okuyup işlediğimizden emin olmak için bazı özel günlükler ekleyelim. Ayrıca, sözü bir hatayla reddedersek hata mesajının Cloud Logging'e de 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ığımızı belirleyebilmemiz için yerel ev 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 derleyip Firebase'e yeniden dağıtmanız gerekir.

$ cd ../app-faulty/local
$ npm run build
$ firebase deploy --only hosting

Şimdi, güncellenen yerel ev 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ğımıza bakalım. Projeniz için Cloud Logging'e 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 Logging > Logs Explorer'ı (Günlük Gezgini) seçin.

Günlük verilerine erişim, entegrasyon projenizin kullanıcıları için Identity and Access Management (IAM) aracılığıyla yönetilir. Günlük verileri için roller ve izinler hakkında daha fazla bilgi edinmek istiyorsanız 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 olduğunu biliyoruz. Ancak sorunun tam olarak ne olduğunu öğrenmek istiyoruz. Bu nedenle, önce IDENTIFY işleyicisinde oluşan hataları filtreleyelim.

Sorguyu göster açma/kapatma düğmesini tıklayın. Bu düğme, Sorgu oluşturucu kutusuna dönüşür. Sorgu oluşturucu kutusuna jsonPayload.intent="IDENTIFY" girin 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özü reddederken ayarladığınız errorCode ve debugString, IDENTIFY işleyicisinde yer alır.

debugString, yerel cihaz kimliğinin beklenen biçimde olmadığını gösteriyor. Local Home uygulaması, yerel cihaz kimliğini deviceid ile başlayıp 3 rakamla devam eden bir dize olarak almayı bekliyor ancak buradaki yerel cihaz kimliği bir onaltılık dize.

Hatayı düzeltin

Tarama verilerinden yerel cihaz kimliğini ayrıştırdığımız kaynak koda geri döndüğümüzde, dizeyi baytlara dönüştürürken kodlamayı sağlamadığımızı fark ederiz. Tarama verileri onaltılık dize olarak alındığından Buffer.from() işlevi çağrılırken karakter kodlaması olarak hex iletilir.

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 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ım işleminden sonra, güncellenen 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örmemeniz gerekir.

Artık cihazınıza tekrar komut göndermeyi deneyebilirsiniz.

"Ok Google, force local."

"Ok Google, çamaşır makinem durdurulsun."

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

...

"Ok Google, varsayılanı zorla."

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

Google Home uygulamasındaki dokunma kontrollerini veya sesli komutları kullanarak cihazınızı doğruladıktan sonra, entegrasyonunuzla ilişkili cihaz türlerine ve özelliklerine dayalı kullanım alanlarını doğrulamak için otomatik Test Suite for smart home'u kullanabilirsiniz. Test paketi, entegrasyonunuzdaki sorunları tespit etmek için bir dizi test çalıştırır ve başarısız olan test senaryoları için bilgilendirici mesajlar göstererek etkinlik günlüklerine girmeden önce hata ayıklama işleminizi hızlandırır.

Akıllı ev için test paketini çalıştırma

Test Paketi ile buluttan buluta entegrasyonunuzu test etmek için aşağıdaki talimatları uygulayın:

1. Web tarayıcınızda Test Suite for smart home'u (Akıllı Ev için Test Paketi) 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, Cloud'dan Cloud'a entegrasyonunuzun proje kimliğini girin. Devam etmek için SONRAKİ'yi tıklayın.
4. Test Ayarları adımındaki Cihazlar ve Tepsiler bölümünde Arızalı Çamaşır Makinenizi görmeniz gerekir.
5. Örnek çamaşır makinesi uygulamasında çamaşır makinesi ekleme / kaldırma / yeniden adlandırma için kullanıcı arayüzü olmadığından Test Request Sync seçeneğini devre dışı bırakın. Bir üretim sisteminde, kullanıcı cihaz eklediğinde, kaldırdığında veya yeniden adlandırdığında Senkronizasyon İste'yi tetiklemeniz gerekir.
6. Hem yerel hem de bulut yollarını test edeceğimiz için Yerel Ev SDK'sı seçeneğini etkin bırakın.
7. Testi çalıştırmaya başlamak için Sonraki: Test ortamı'nı tıklayın.

Testler tamamlandığında, yerel yoldaki testleri duraklatma/devam ettirme işlemlerinin başarısız olduğunu, bulut yolundaki testleri duraklatma/devam ettirme işlemlerinin ise başarılı olduğunu görürsünüz.

Hata mesajını analiz etme

Başarısız olan test senaryolarındaki hata mesajlarını daha yakından inceleyin. Bu testler, beklenen durumu ve gerçek durumu gösterir. Bu durumda, "Çamaşır makinesini duraklat" için beklenen durum isPaused: true iken gerçek durumda isPaused: false yanıtını aldık. Benzer şekilde, "Çamaşır makinesini duraklat" için beklenen durum isPaused: true iken gerçek durumda isPaused: false yanıtı alındı.

Hata mesajlarından, yerel yolda isPaused durumunu tersine ayarladığımız anlaşılıyor.

Hatayı tespit edip 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 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 değerini gerçekten de ters durumda ayarlıyoruz. params.pause değeri true olduğunda true, aksi takdirde false 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 içinde şu komutu çalıştırın:

$ npm run build
$ firebase deploy --only hosting

Şimdi, güncellenen 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 senaryolarının başarılı olduğunu göreceksiniz.

7. Tebrikler

Tebrikler! Akıllı ev için Test Paketi ve Cloud Logging'i kullanarak Local Home uygulamasında sorun gidermeyi başarıyla öğrendiniz.

Daha Fazla Bilgi

Deneyebileceğiniz diğer yöntemler:

• Cihazınıza daha fazla desteklenen özellik ekleyin ve Test Paketi ile test edin.
• Her amaç işleyicisine daha fazla özel günlük ekleyin ve bunları Cloud Logging'de görüntüleyin.
• Entegrasyonunuzla ilgili faydalı kullanım metrikleri elde etmek için kontrol panelleri oluşturun, uyarılar ayarlayın ve metrik verilerine programatik olarak erişin.

Entegrasyonunuzu kullanıcılarla paylaşmak için gereken sertifika süreci de dahil olmak üzere, entegrasyonları test etme ve incelemeye gönderme hakkında daha fazla bilgi edinebilirsiniz.