Report State, Home işleminin bir QUERY
amacı beklemek yerine kullanıcının cihazının son durumunu proaktif olarak Google Home Graph adlı kullanıcıya bildirmesini sağlayan önemli bir özelliktir.
Report State, kullanıcı cihazlarıyla ilişkilendirilmiş ve belirtilen agentUserId
olduğu sürece bu cihazların durumunu Google'a bildirir (orijinal SYNC
isteğinde gönderilir). Google Assistant, bir cihazın mevcut durumunu anlamayı gerektiren bir işlem yapmak istediğinde, EXECUTE
amacını yayınlamadan önce çeşitli üçüncü taraf bulutlara QUERY
niyeti göndermek yerine Home Graph içinde durum bilgisini arayabilir.
Report State kullanılmadığında, bir oturma odasındaki birden fazla sağlayıcıdan gelen ışıklar göz önünde bulundurulduğunda Ok Google, salonumun parlaklığını artır komutu, daha önce bildirilenlere göre mevcut parlaklık değerlerini aramak yerine, birden çok buluta gönderilen birden çok QUERY
amacını çözmeyi gerektirir. En iyi kullanıcı deneyimi için Assistant uygulamasının mevcut durumda olması gerekir. Bu durumda cihaza gidiş geliş gerekmez.
Bir cihaz için ilk SYNC
değerinin ardından platform, Home Graph alanını doldurmak için cihazın durumunu toplayan bir QUERY
amacı gönderir.
Bu noktadan sonra Home Graph, yalnızca Report State ile gönderilen durumu depolar.
Report State çağırırken belirli bir özellik için tam durum verileri sağladığınızdan emin olun. Home Graph, durumları özellik başına günceller ve bir Report State çağrısı yapıldığında bu özellik için tüm verilerin üzerine yazar. Örneğin, StartStop özelliği için durum raporluyorsanız yükün hem isRunning
hem de isPaused
değerlerini içermesi gerekir.
Başlayın
Report State uygulamak için aşağıdaki adımları izleyin:
Google Home Graph API'yi etkinleştirin
-
Google Cloud Console sayfasında HomeGraph API sayfasına gidin.
Home Graph API sayfasına gidin - smart home proje kimliğinizle eşleşen projeyi seçin.
- ETKİNLEŞTİR'i tıklayın.
Hizmet Hesabı Anahtarı Oluşturma
Google Cloud Console uygulamasından bir hizmet hesabı anahtarı oluşturmak için şu talimatları uygulayın:
-
Google Cloud Console sayfasında Hizmet hesabı anahtarı oluştur sayfasına gidin.
Hizmet Hesabı Anahtarı Oluşturun sayfasına gidin - Hizmet hesabı listesinden Yeni hizmet hesabı'nı seçin.
- Hizmet hesabı adı alanına bir ad girin.
- Hizmet hesabı kimliği alanına bir kimlik girin.
Rol listesinden Hizmet Hesapları > Hizmet Hesabı Jetonu Oluşturucu'yu seçin.
Anahtar türü olarak JSON seçeneğini belirleyin.
- Oluştur'u tıklayın. Anahtarınızı içeren bir JSON dosyası bilgisayarınıza indirilir.
API'yi çağırma
Aşağıdaki sekmelerden bir seçenek belirleyin:
HTTP
Home Graph, bir HTTP uç noktası sağlar
- İndirilen hizmet hesabı JSON dosyasını kullanarak JSON Web Token (JWT) oluşturun. Daha fazla bilgi için bkz. Hizmet Hesabı Kullanarak Kimlik Doğrulama.
- oauth2l kullanarak
https://www.googleapis.com/auth/homegraph
kapsamında bir OAuth 2.0 erişim jetonu alın: - JSON isteğini
agentUserId
ile oluşturun. Rapor Durumu ve Bildirim için örnek bir JSON isteği aşağıda verilmiştir: - Rapor Durumu ve Bildirim JSON dosyasını ve HTTP POST isteğinizdeki jetonu Google Home Graph uç noktasıyla birleştirin. Aşağıda, test olarak
curl
kullanarak komut satırında nasıl istekte bulunulacağına dair bir örnek verilmiştir:
oauth2l fetch --credentials service-account.json \ --scope https://www.googleapis.com/auth/homegraph
{ "requestId": "123ABC", "agentUserId": "user-123", "payload": { "devices": { "states": { "light-123": { "on": true } } } } }
curl -X POST -H "Authorization: Bearer ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d @request-body.json \ "https://homegraph.googleapis.com/v1/devices:reportStateAndNotification"
gRPC
Home Graph, bir gRPC uç noktası sağlar
- Home Graph API için protokol arabellek hizmeti tanımını öğrenin.
- Desteklenen dillerden biri için istemci saplaması oluşturmak üzere gRPC geliştirici dokümanlarındaki talimatları uygulayın.
- ReportStateAndNotification yöntemini çağırın.
Node.js
Google API'leri Node.js İstemcisi, Home Graph API'sı için bağlantılar sağlar.
- Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak
google.homegraph
hizmetini başlatın. reportStateAndNotification
yöntemini ReportStateAndNotificationRequest ile çağırın. ReportStateAndNotificationResponse içeren birPromise
döndürür.
const homegraphClient = homegraph({ version: 'v1', auth: new GoogleAuth({ scopes: 'https://www.googleapis.com/auth/homegraph' }) }); const res = await homegraphClient.devices.reportStateAndNotification({ requestBody: { agentUserId: 'PLACEHOLDER-USER-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { states: { "PLACEHOLDER-DEVICE-ID": { on: true } } } } } });
Java
HomeGraph API Client Library for Java, Home Graph API için bağlantılar sağlar.
- Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak
HomeGraphApiService
hizmetini başlatın. ReportStateAndNotificationRequest
ilereportStateAndNotification
yöntemini çağırın. BirReportStateAndNotificationResponse
döndürür.
// Get Application Default credentials. GoogleCredentials credentials = GoogleCredentials.getApplicationDefault() .createScoped(List.of("https://www.googleapis.com/auth/homegraph")); // Create Home Graph service client. HomeGraphService homegraphService = new HomeGraphService.Builder( GoogleNetHttpTransport.newTrustedTransport(), GsonFactory.getDefaultInstance(), new HttpCredentialsAdapter(credentials)) .setApplicationName("HomeGraphExample/1.0") .build(); // Build device state payload. Map<?, ?> states = Map.of("on", true); // Report device state. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setStates(Map.of("PLACEHOLDER-DEVICE-ID", states)))); homegraphService.devices().reportStateAndNotification(request); }
Test Raporu Durumu
İşleminizi sertifika almaya hazırlamak için Report State testini yapmanız önemlidir.
Bunun için, indirme veya dağıtım gerektirmeyen bağımsız bir web uygulaması olan Home Graph Görüntüleyici aracını kullanmanızı öneririz.
Report State Kontrol Paneli hâlâ kullanılabilir olsa da kullanımdan kaldırıldı ve artık desteklenmiyor.
Rapor Durumu Kontrol Paneli
Ön koşullar
İşleminizi test edebilmeniz için Hizmet Hesabı Anahtarınıza ve agentUserId
hizmetinize ihtiyacınız vardır. Hizmet hesabı anahtarınız zaten varsa veagentUserId
Report StateKontrol Paneli'ni dağıtma başlıklı makaleyi inceleyin.
Rapor Durumu kontrol panelini dağıtma
Projeniz için Hizmet Hesabı Anahtarını ve Aracı User-ID'sini edindikten sonra Report State Kontrol Paneli'nden en son sürümü indirip dağıtın.
En son sürümü indirdikten sonra, eklenen README.MD
dosyasındaki talimatları uygulayın.
Report State kontrol panelini dağıttıktan sonra aşağıdaki URL'den kontrol paneline erişin (your_project_id kısmını proje kimliğinizle değiştirin):
http://<your-project-id>.appspot.com
Kontrol panelinde aşağıdakileri yapın:
- Hesap Anahtar Dosyanızı seçin
- AgentUserId'nizi ekleyin
Ardından Liste'yi tıklayın.
Tüm cihazlarınız listelenir. Liste doldurulduktan sonra, cihaz durumlarını güncellemek için Yenile düğmesini kullanabilirsiniz. Cihazın durumunda bir değişiklik olursa satır yeşil renkle vurgulanır.
Hata Yanıtları
Report State numaralı telefonu aradığınızda aşağıdaki hata yanıtlarından birini alabilirsiniz. Bu yanıtlar HTTP durum kodları biçiminde gelir.
400 Bad Request
- Sunucu, geçersiz söz dizimi nedeniyle istemci tarafından gönderilen isteği işleyemedi. Yaygın nedenler arasında bozuk JSON veya bir dize değeri için "" yerinenull
kullanımı yer alır.404 Not Found
: İstenen kaynak bulunamadı ancak ileride kullanıma sunulabilir. Bu durum genellikle istenen cihazı bulamadığımız anlamına gelir. Bu durum, kullanıcı hesabının Google'a bağlı olmadığı veya geçersiz biragentUserId
aldığımız anlamına da gelebilir.agentUserId
değerinin SYNC yanıtınızda sağlanan değerle eşleştiğinden ve DISCONNECT amaçlarını düzgün bir şekilde işlediğinizden emin olun.