Bildirimler, smart home İşleminizin kullanıcılar ile cihaz hakkındaki önemli etkinlikler veya değişiklikler hakkında iletişim kurmak için Google Assistant kullanmasına olanak tanır. Kullanıcıları zamanında cihaz etkinlikleri (örneğin, kapıdayken) veya bir cihaz kilidi değişiminin başarıyla etkileşimde bulunması ya da sıkışması gibi istenen bir cihaz durumu değişikliği hakkında rapor oluşturmak için bildirimleri uygulayabilirsiniz.
smart home İşleminiz kullanıcılara aşağıdaki bildirim türlerini gönderebilir:
Proaktif bildirimler: Cihazlarına kullanıcı isteği (ör. kapı zilinin çalması) olmadan kullanıcıyı bir smart home cihaz etkinliği hakkında uyarır.
Takip yanıtları: Bir cihaz komutu isteğinin başarılı veya başarısız olduğunun onaylanması (ör. bir kapıyı kilitlerken). Tamamlanması zaman alan cihaz komutları için bu uyarıları kullanın. Takip yanıtları, yalnızca akıllı hoparlörlerden ve akıllı ekranlardan cihaz komutu istekleri gönderildiğinde desteklenir.
Assistant, bu bildirimleri kullanıcılara akıllı hoparlörler ve akıllı ekranlarda duyuru olarak sunar. Proaktif bildirimler varsayılan olarak kapalıdır. Kullanıcılar, Google Home app (GHA)'ten gelen tüm proaktif bildirimleri etkinleştirebilir veya devre dışı bırakabilir.
Bildirimleri tetikleyen etkinlikler
Cihaz etkinlikleri gerçekleştiğinde, Sipariş karşılama siparişiniz Google'a bir bildirim isteği gönderir. smart home İşleminizin desteklediği cihaz özellikleri, ne tür bildirim etkinliklerinin kullanılabileceğini ve bu bildirimlere ekleyebileceğiniz verileri belirler.
Aşağıdaki özellikler proaktif bildirimleri destekler:
Özellik | Etkinlikler |
---|---|
Nesne Algılama | Kapıda tanıdık bir yüz algılanması gibi, cihaz tarafından algılanan nesneler. Örneğin: "Ayşe ve Burak ön kapıda." |
RunCycle | Cihaz bir döngüyü tamamlar. Örneğin: "Çamaşır makinesi döngüsü tamamlandı." |
SensorState | Cihaz, desteklenen bir sensör durumu algılar. Örneğin: "Duman dedektörü duman algıladı." |
Sıcaklık Kontrolü | Cihaz bir sıcaklığa ayarlanıyor. Örneğin: "Fırın önceden 350 dereceye kadar ısıtıldı." |
Ulusal Güçlendirme | Sistem, giriş geri sayımıyla birlikte alarm öncesi bir duruma geçer ve açık bir kapıyla tetiklenir. |
KameraCanlı Yayın | Cihaz tarafından bir nesne veya hareket algılandıktan sonra kameranın canlı yayınına bağlantı verin. |
MotionDetection | "Hareket, 1 Temmuz 2020, 12:00'da algılandı." |
Aşağıdaki özellikler takip yanıtlarını destekler:
Özellik | Etkinlikler |
---|---|
Ulusal Güçlendirme | action.devices.commands.ArmDisarm cihaz komutunun yürütülmesinin ardından tamamlanma durumu ve durum değişikliği. Örneğin:
"Güvenlik sistemi etkinleştirildi."
|
Kilit Kilidi | action.devices.commands.LockUnlock cihaz komutunun yürütülmesinin ardından tamamlanma durumu ve durum değişikliği. Örneğin: "Ön kapı kilitli" veya "Ön kapı sıkışmış."
|
Ağ Kontrolü | action.devices.commands.TestNetworkSpeed cihaz komutunun yürütülmesinin ardından tamamlanma durumu ve durum değişikliği. Örneğin: "Ağ hız testiniz tamamlandı. Ofis yönlendiricisinin indirme hızı şu anda 80,2 Kb/sn ve yükleme hızı 9,3 Kb/sn."
|
OpenClose | action.devices.commands.OpenClose cihaz komutunun yürütülmesinin ardından tamamlanma durumu ve durum değişikliği. Örneğin: "Ön kapı açıldı" veya "Ön kapı açılamadı."
|
Başlatma | action.devices.commands.StartStop cihaz komutunun yürütülmesinin ardından tamamlanma durumu ve durum değişikliği. Örneğin: "Elektrik süpürgesi başlatıldı."
|
Tüm cihaz türleri, geçerli özelliklerle ilgili bildirimleri destekler.
Akıllı ev İşleminiz için bildirimler oluşturun
smart home İşlemlerinize şu aşamalarda bildirim ekleyin:
- smart home cihaz uygulamanızdan bildirimlerin etkinleştirilip etkinleştirilmediğini Google'a bildirin. Kullanıcılar uygulamanızda bildirimleri açar veya kapatırsa cihaz değişikliğini Google'a bildirmek için bir
SYNC
isteği gönderin. - Bir bildirimi tetikleyen alakalı bir cihaz etkinliği veya durum değişikliği olduğunda Report State
reportStateAndNotification
API'sini çağırarak bildirim isteği gönderin. Cihaz durumu değiştiyse Report State ve Bildirim çağrılarınızda hem durum hem bildirim yükünü birlikte gönderebilirsiniz.
Aşağıdaki bölümlerde bu adımlar daha ayrıntılı olarak ele alınmaktadır.
Uygulamanızda bildirimlerin etkinleştirilip etkinleştirilmediğini belirtme
Kullanıcılar GHA uygulamasında bu özelliği etkinleştirerek proaktif bildirimler almak isteyip istemediklerini seçebilir. Dilerseniz smart home kullanıcısının uygulamasına, kullanıcıların bildirimleri cihaz üzerinden (ör. uygulama ayarlarından) açıkça değiştirmelerini de sağlayabilirsiniz.
Cihaz verilerini güncellemek için bir SYNC isteğinde bulunun çağrısı yaparak cihazınızda bildirimlerin etkinleştirildiğini Google'a bildirin. Kullanıcılar uygulamanızda bu ayarı her değiştirdiğinde buna benzer bir SYNC
isteği göndermeniz gerekir.
SYNC
yanıtınızda aşağıdaki güncellemelerden birini gönderin:
- Kullanıcı, cihaz uygulamanızda bildirimleri açık bir şekilde açmışsa veya bir açma/kapatma seçeneği sunmuyorsanız
devices.notificationSupportedByAgent
özelliğinitrue
olarak ayarlayın. - Kullanıcı, cihaz uygulamanızda bildirimleri açıkça devre dışı bıraktıysa
devices.notificationSupportedByAgent
özelliğinifalse
olarak ayarlayın.
Aşağıdaki snippet'te SYNC yanıtınızın nasıl ayarlanacağına ilişkin bir örnek gösterilmektedir:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
Google'a bildirim isteği gönderme
Assistant uygulamasında bildirimleri tetiklemek için karşılamanız, Report State ve Notification API çağrısı yoluyla Google Home Graph adresine bildirim yükü gönderir.
Google HomeGraph API'yi etkinleştirme
-
Google Cloud Console içinde HomeGraph API sayfasına gidin.
HomeGraph 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 üzerinden hizmet hesabı anahtarı oluşturmak için aşağıdaki talimatları uygulayın:
-
Google Cloud Console bölümünde Hizmet hesabı anahtarı oluştur sayfasına gidin.
Hizmet Hesabı Anahtarı Oluştur sayfasına git - Hizmet hesabı listesinden Yeni hizmet hesabı'nı seçin.
- Service account name (Hizmet hesabı adı) alanına bir ad girin.
- Service account ID (Hizmet hesabı kimliği) alanına bir kimlik girin.
Rol listesinden Hizmet Hesapları > Hizmet Hesabı Jeton Oluşturucu'yu seçin.
Anahtar türü için JSON seçeneğini belirleyin.
- Oluştur'u tıklayın. Anahtar indirmelerinizi içeren bir JSON dosyası bilgisayarınıza indirilir.
Bildirimi gönder
devices.reportStateAndNotification
API'yi kullanarak bildirim isteğinde bulunun.
JSON isteğinizde, bildirimi tetikleyen etkinlik için platformunuz tarafından oluşturulan benzersiz bir kimlik olan bir eventId
bulunmalıdır. eventId
, her bildirim isteği gönderdiğinizde farklı olan rastgele bir kimlik olmalıdır.
API çağrınızda geçirdiğiniz notifications
nesnesine bildirimin nasıl sunulması gerektiğini tanımlayan bir priority
değeri ekleyin. notifications
nesneniz, cihaz özelliğine bağlı olarak farklı alanlar içerebilir.
Yükü ayarlamak ve API'ye çağrıda bulunmak için aşağıdaki yöntemlerden birini uygulayın:
Proaktif bildirim yükü gönderme
API'yi çağırmak için aşağıdaki sekmelerden birini seçin:
HTTP
Home Graph API, bir HTTP uç noktası sağlar
- İndirilen hizmet hesabı JSON dosyasını kullanarak bir JSON Web Token (JWT) oluşturun. Daha fazla bilgi için Hizmet Hesabı Kullanarak Kimlik Doğrulama bölümüne bakın.
- oauth2l kullanarak
https://www.googleapis.com/auth/homegraph
kapsamıyla bir OAuth 2.0 erişim jetonu edinin: agentUserId
ile JSON isteği oluşturun. Report State ve Bildirim için örnek bir JSON isteği:- Report State ve Bildirim JSON ile HTTP POST isteğinizdeki jetonu Google Home Graph uç noktasına kadar birleştirin. Aşağıda, test olarak
curl
öğesini 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
{ "agentUserId": "PLACEHOLDER-USER-ID", "eventId": "PLACEHOLDER-EVENT-ID", "requestId": "PLACEHOLDER-REQUEST-ID", "payload": { "devices": { "notifications": { "PLACEHOLDER-DEVICE-ID": { "ObjectDetection": { "priority": 0, "detectionTimestamp": 1534875126750, "objects": { "named": [ "Alice" ], "unclassified": 2 } } } } } } }
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 API, bir gRPC uç noktası sağlar
- Home Graph API için protokol arabelleği hizmet tanımını alın.
- Desteklenen dillerden biri için istemci saplaması oluşturmak üzere gRPC geliştirici belgelerini uygulayın.
- ReportStateAndNotification yöntemini çağırın.
Node.js
Google API'leri Node.js İstemcisi, Home Graph API'si için bağlamalar sağlar.
- Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak
google.homegraph
hizmetini başlatın. - ReportStateAndNotificationRequest ile
reportStateAndNotification
yöntemini çağırın. ReportStateAndNotificationResponse ile 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', eventId: 'PLACEHOLDER-EVENT-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { notifications: { 'PLACEHOLDER-DEVICE-ID': { ObjectDetection: { priority: 0, detectionTimestamp: 1534875126750, objects: { named: ['Alice'], unclassified: 2 } } } } } } } });
Java
Java için HomeGraph API İstemci Kitaplığı, Home Graph API için bağlamalar sağlar.
- Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak
HomeGraphApiService
'i başlatın. ReportStateAndNotificationRequest
ilereportStateAndNotification
yöntemini çağırın.ReportStateAndNotificationResponse
değerini 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 notification payload. Map<?, ?> notifications = Map.of( "ObjectDetection", Map.of( "priority", 0, "detectionTimestamp", 1534875126, "objects", Map.of("named", List.of("Alice"), "unclassifed", 2))); // Send notification. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setEventId("PLACEHOLDER-EVENT-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", notifications)))); homegraphService.devices().reportStateAndNotification(request);
Takip yanıtı yükü gönderme
Takip yanıtı yükü, isteğin durumunu, varsa etkinlik hataları için hata kodlarını ve EXECUTE
intent isteği sırasında sağlanan geçerli followUpToken
değerini içerir. followUpToken
öğesinin geçerli kalması ve yanıtı orijinal istekle doğru şekilde ilişkilendirmek için beş dakika içinde kullanılması gerekir.
Aşağıdaki snippet'te followUpToken
alanı olan örnek bir EXECUTE
istek yükü gösterilmektedir.
{ "requestId": "ff36a3cc-ec34-11e6-b1a0-64510650abcf", "inputs": [{ "intent": "action.devices.EXECUTE", "payload": { "commands": [{ "devices": [{ "id": "123", }], "execution": [{ "command": "action.devices.commands.TestNetworkSpeed", "params": { "testDownloadSpeed": true, "testUploadSpeed": false, "followUpToken": "PLACEHOLDER" } }] }] } }] };
Google, followUpToken
değerini sadece kullanıcının ilk olarak etkileşimde bulunduğu cihazda yayınlamak ve kullanıcının tüm cihazlarında yayınlamak için kullanır.
API'yi çağırmak için aşağıdaki sekmelerden birini seçin:
HTTP
Home Graph API, bir HTTP uç noktası sağlar
- İndirilen hizmet hesabı JSON dosyasını kullanarak bir JSON Web Token (JWT) oluşturun. Daha fazla bilgi için Hizmet Hesabı Kullanarak Kimlik Doğrulama bölümüne bakın.
- oauth2l kullanarak
https://www.googleapis.com/auth/homegraph
kapsamıyla bir OAuth 2.0 erişim jetonu edinin: agentUserId
ile JSON isteği oluşturun. Report State ve Bildirim için örnek bir JSON isteği:- Report State ve Bildirim JSON ile HTTP POST isteğinizdeki jetonu Google Home Graph uç noktasına kadar birleştirin. Aşağıda, test olarak
curl
öğesini 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
{ "agentUserId": "PLACEHOLDER-USER-ID", "eventId": "PLACEHOLDER-EVENT-ID", "requestId": "PLACEHOLDER-REQUEST-ID", "payload": { "devices": { "notifications": { "PLACEHOLDER-DEVICE-ID": { "NetworkControl": { "priority": 0, "followUpResponse": { "status": "SUCCESS", "followUpToken": "PLACEHOLDER", "networkDownloadSpeedMbps": 23.3, "networkUploadSpeedMbps": 10.2 } } } } } } }
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 API, bir gRPC uç noktası sağlar
- Home Graph API için protokol arabelleği hizmet tanımını alın.
- Desteklenen dillerden biri için istemci saplaması oluşturmak üzere gRPC geliştirici belgelerini uygulayın.
- ReportStateAndNotification yöntemini çağırın.
Node.js
Google API'leri Node.js İstemcisi, Home Graph API'si için bağlamalar sağlar.
- Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak
google.homegraph
hizmetini başlatın. - ReportStateAndNotificationRequest ile
reportStateAndNotification
yöntemini çağırın. ReportStateAndNotificationResponse ile birPromise
döndürür.
const followUpToken = executionRequest.inputs[0].payload.commands[0].execution[0].params.followUpToken; 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', eventId: 'PLACEHOLDER-EVENT-ID', requestId: 'PLACEHOLDER-REQUEST-ID', payload: { devices: { notifications: { 'PLACEHOLDER-DEVICE-ID': { NetworkControl: { priority: 0, followUpResponse: { status: 'SUCCESS', followUpToken, networkDownloadSpeedMbps: 23.3, networkUploadSpeedMbps: 10.2, } } } } } } } });
Java
Java için HomeGraph API İstemci Kitaplığı, Home Graph API için bağlamalar sağlar.
- Uygulama Varsayılan Kimlik Bilgilerini kullanarak
HomeGraphApiService
öğesini başlatın ReportStateAndNotificationRequest
ilereportStateAndNotification
yöntemini çağırın.ReportStateAndNotificationResponse
değerini 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(); // Extract follow-up token. ExecuteRequest.Inputs executeInputs = (Inputs) executeRequest.getInputs()[0]; String followUpToken = (String) executeInputs .getPayload() .getCommands()[0] .getExecution()[0] .getParams() .get("followUpToken"); // Build device follow-up response payload. Map<?, ?> followUpResponse = Map.of( "NetworkControl", Map.of( "priority", 0, "followUpResponse", Map.of( "status", "SUCCESS", "followUpToken", followUpToken, "networkDownloadSpeedMbps", 23.3, "networkUploadSpeedMbps", 10.2))); // Send follow-up response. ReportStateAndNotificationRequest request = new ReportStateAndNotificationRequest() .setRequestId("PLACEHOLDER-REQUEST-ID") .setAgentUserId("PLACEHOLDER-USER-ID") .setEventId("PLACEHOLDER-EVENT-ID") .setPayload( new StateAndNotificationPayload() .setDevices( new ReportStateAndNotificationDevice() .setNotifications(Map.of("PLACEHOLDER-DEVICE-ID", followUpResponse)))); homegraphService.devices().reportStateAndNotification(request);
Günlük Kaydı
Bildirimler, Cloud Logging ile olay günlüklerine erişme bölümünde belirtildiği şekilde olay günlük kaydını destekler. Bu günlükler, İşleminizde bildirim kalitesini test etmek ve korumak için kullanışlıdır.
Aşağıda notificationLog
girişinin şeması verilmiştir:
Mülk | Açıklama |
---|---|
requestId |
Bildirim isteği kimliği. |
structName |
Bildirim yapısının adı (ör. "ObjectDetection"). |
status |
Bildirimin durumunu belirtir. |
status
alanı, bildirim yükünde hatalara işaret edebilecek çeşitli durumları içerir. Bunlardan bazıları yalnızca üretimde kullanıma sunulmamış Action'larda kullanılabilir.
Örnekler:
Durum | Açıklama |
---|---|
EVENT_ID_MISSING |
Zorunlu eventId alanının eksik olduğunu belirtir.
|
PRIORITY_MISSING |
Bir priority alanının eksik olduğunu belirtir.
|
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
Bildiren cihazın SYNC özelliğinde sağlanan notificationSupportedByAgent özelliğinin yanlış olduğunu belirtir.
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Kullanıcının, bildirim gönderen cihazda GHA içindeki bildirimleri etkinleştirmediğini gösterir. Bu durum yalnızca üretime sunulmamış İşlemler'de kullanılabilir. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
Kullanıcının, bildirim yapan cihazı bir eve/yapıya atamadığını belirtir. Bu durum yalnızca üretime sunulmamış İşlemler'de kullanılabilir. |
Tüm alanlara uygulanabilecek bu genel durumlara ek olarak status
alanı, özelliğe (ör. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
) göre özelliğe özgü durumları da içerebilir.