Bildirimler, smart home İşleminizin Google Assistant aracılığıyla kullanıcılarla ilgili önemli etkinlikler veya değişiklikler hakkında kullanıcılarla iletişim kurmasına olanak tanır. Cihaz etkinlikleri konusunda kullanıcıları uyarmak için bildirimler uygulayabilirsiniz. Örneğin, birisi kapıya geldiğinde veya cihaz durumundaki talep edilen bir değişikliği (ör. kapı kilidi sürgüsünün başarılı bir şekilde devreye girmesi veya sıkışması) ilgili olarak bildirebilirsiniz.
smart home İşleminiz kullanıcılara aşağıdaki bildirim türlerini gönderebilir:
Proaktif bildirimler: Kullanıcının cihazına önceden herhangi bir istekte bulunmadığı (ör. kapı zilinin çalması) kullanıcıyı smart home cihaz etkinliği konusunda uyarır.
Takip yanıtları: Bir cihaz komut isteğinin başarılı veya başarısız olduğunun onayı (örneğin, bir kapı kilitlenirken). Tamamlanması zaman alan cihaz komutları için bu uyarıları kullanın. Takip yanıtları, yalnızca cihaz komutu istekleri akıllı hoparlörlerden ve akıllı ekranlardan gönderildiğinde desteklenir.
Assistant, bu bildirimleri akıllı hoparlörlerde ve akıllı ekranlarda duyuru olarak kullanıcılara sağlar. Proaktif bildirimler varsayılan olarak devre dışıdır. Kullanıcılar, tüm proaktif bildirimleri Google Home app (GHA) üzerinden etkinleştirebilir veya devre dışı bırakabilir.
Bildirimleri tetikleyen etkinlikler
Cihaz etkinlikleri gerçekleştiğinde, İşleminiz Google'a bir bildirim isteği gönderir. smart home İşleminizin desteklediği cihaz özellikleri, ne tür bildirim etkinliklerinin olduğunu ve bu bildirimlere ekleyebileceğiniz verileri belirler.
Aşağıdaki özellikler proaktif bildirimleri destekler:
Özellik | Etkinlikler |
---|---|
ObjectDetection | Kapıda tanınan bir yüz algılanması gibi cihaz tarafından algılanan nesneler. Örneğin: "Ali ve Bora ön kapıda." |
RunCycle | Cihaz bir döngüyü tamamlar. Örneğin: "Çamaşır makinesinin devri tamamlandı." |
SensorState | Cihaz, desteklenen bir sensör durumu algıladı. Örneğin: "Duman dedektörü duman algıladı." |
TemperatureControl | Cihaz, istenen sıcaklık ayarına ulaştı. Örneğin: "Fırın önceden 350 dereceye ısıtıldı." |
ArmDisarm | Sistem, açık bir kapının tetiklediği giriş geri sayımıyla alarm öncesi duruma girer. |
CameraStream | Cihaz bir nesne veya hareket algıladığında kameranın canlı yayınına bağlantı verir. |
MotionDetection | "1 Temmuz 2020, saat 12:00'de hareket algılandı." |
Aşağıdaki özellikler takip yanıtlarını destekler:
Özellik | Etkinlikler |
---|---|
ArmDisarm | action.devices.commands.ArmDisarm cihaz komutu çalıştırıldıktan sonra tamamlanma durumu ve durum değişikliği Örneğin:
"Güvenlik sistemi etkinleştirildi."
|
LockUnlock | action.devices.commands.LockUnlock cihaz komutu çalıştırıldıktan sonra tamamlanma durumu ve durum değişikliği Örneğin: "Ön kapı kilitlendi" veya "Ön kapı sıkışmış."
|
NetworkControl | action.devices.commands.TestNetworkSpeed cihaz komutu çalıştırıldıktan sonra 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, yükleme hızı ise 9,3 Kb/sn."
|
OpenClose | action.devices.commands.OpenClose cihaz komutu çalıştırıldıktan sonra tamamlanma durumu ve durum değişikliği Örneğin: "Ön kapı açıldı" veya "Ön kapı açılamadı."
|
StartStop | action.devices.commands.StartStop cihaz komutu çalıştırıldıktan sonra 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 işleminiz için bildirimler oluşturma
smart home İşleminize ş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 Google'a cihaz değişikliği hakkında bilgi vermek için
SYNC
isteği gönderin. - Bildirimi tetikleyen ilgili bir cihaz etkinliği veya durum değişikliği gerçekleştiğinde Report State
reportStateAndNotification
API'sini çağırarak bildirim isteği gönderin. Cihaz durumu değiştiyse Report State ve Bildirim çağrınızda hem durum hem de 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 belirtin
Kullanıcılar, GHA'da bu özelliği etkinleştirerek proaktif bildirim almak isteyip istemediklerini seçebilirler. smart home cihazınızın uygulamasında, isteğe bağlı olarak kullanıcıların cihazdan bildirimleri açıkça açıp kapatmalarına (örneğin, uygulama ayarlarınızdan) olanak tanıyabilirsiniz.
Cihaz verilerini güncellemek için Request SYNC çağrısı yaparak cihazınız için bildirimlerin etkinleştirildiğini Google'a bildirin. Kullanıcılar uygulamanızda bu ayarı her değiştirdiğinde bunun gibi bir SYNC
isteği göndermeniz gerekir.
SYNC
yanıtınızda şu güncellemelerden birini gönderin:
- Kullanıcı, cihaz uygulamanızda bildirimleri açıkça etkinleştirdiyse veya bir açma/kapatma seçeneği görmüyorsanı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ı nasıl ayarlayacağınıza dair bir örnek gösterilmektedir:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
Google'a bildirim istekleri gönderme
Sipariş karşılama, Assistant üzerinden bildirimlerin tetiklenmesi için Report State ve Notification API çağrısı aracılığıyla Google Home Graph'a bir bildirim yükü gönderir.
Google HomeGraph API'yi etkinleştirme
-
Google Cloud Console uygulamasında 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 öğesinden 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şturma sayfasına git - 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.
Role (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.
Bildirimi gönder
Bildirim isteği çağrısını devices.reportStateAndNotification
API'yi kullanarak yapın.
JSON isteğiniz, bir eventId
içermelidir. Bu, bildirimi tetikleyen etkinlik için platformunuz tarafından oluşturulan benzersiz bir kimliktir. eventId
, her bildirim isteği gönderdiğinizde farklı olan rastgele bir kimlik olmalıdır.
API çağrınızda ilettiğ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'yi çağırmak için aşağıdaki yollardan birini izleyin:
Proaktif bildirim yükü gönder
API'yi çağırmak için aşağıdaki sekmelerin birinden bir seçenek belirleyin:
HTTP
Home Graph API, 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ıyla bir OAuth 2.0 erişim jetonu alın: agentUserId
ile JSON isteğini oluşturun. Aşağıda, Report State ve Bildirim için örnek bir JSON isteği verilmiştir:- HTTP POST isteğinizdeki Report State ve Notification JSON kodları ile jetonu Google Home Graph uç noktasına birleştirin. Test amacıyla
curl
kullanarak komut satırında nasıl istek yapacağınıza dair bir örneği aşağıda bulabilirsiniz:
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'sinin protokol arabellekleri hizmeti tanımını alın.
- Desteklenen dillerden biri için istemci saplaması oluşturmak üzere gRPC geliştirici belgelerini izleyin.
- ReportStateAndNotification yöntemini çağırın.
Node.js
Google API'leri Node.js İstemcisi Home Graph API için bağlamalar sağlar.
- Application Default Credentials'ı (Uygulama Varsayılan Kimlik Bilgileri) 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.
- Application Default Credentials'ı (Uygulama Varsayılan Kimlik Bilgileri) kullanarak
HomeGraphApiService
'ı başlatın. ReportStateAndNotificationRequest
ilereportStateAndNotification
yöntemini çağırın.ReportStateAndNotificationResponse
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ının yükü; isteğin durumunu, varsa etkinlik hatalarının hata kodlarını ve EXECUTE
intent isteği sırasında sağlanan geçerli followUpToken
değerini içerir. followUpToken
öğesinin, geçerli durumda kalması ve yanıtı orijinal istekle düzgün şekilde ilişkilendirebilmesi için beş dakika içinde kullanılması gerekir.
Aşağıdaki snippet'te followUpToken
alanı içeren ö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, bildirim çıkışını yalnızca kullanıcının ilk başta etkileşim kurduğu cihazda yapmak için followUpToken
kullanarak kullanıcının tüm cihazlarında yayınlamaz.
API'yi çağırmak için aşağıdaki sekmelerin birinden bir seçenek belirleyin:
HTTP
Home Graph API, 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ıyla bir OAuth 2.0 erişim jetonu alın: agentUserId
ile JSON isteğini oluşturun. Aşağıda, Report State ve Bildirim için örnek bir JSON isteği verilmiştir:- HTTP POST isteğinizdeki Report State ve Notification JSON kodları ile jetonu Google Home Graph uç noktasına birleştirin. Test amacıyla
curl
kullanarak komut satırında nasıl istek yapacağınıza dair bir örneği aşağıda bulabilirsiniz:
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'sinin protokol arabellekleri hizmeti tanımını alın.
- Desteklenen dillerden biri için istemci saplaması oluşturmak üzere gRPC geliştirici belgelerini izleyin.
- ReportStateAndNotification yöntemini çağırın.
Node.js
Google API'leri Node.js İstemcisi Home Graph API için bağlamalar sağlar.
- Application Default Credentials'ı (Uygulama Varsayılan Kimlik Bilgileri) 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.
- Application Default Credentials (Uygulama Varsayılan Kimlik Bilgilerini) kullanarak
HomeGraphApiService
hizmetini başlatın. ReportStateAndNotificationRequest
ilereportStateAndNotification
yöntemini çağırın.ReportStateAndNotificationResponse
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 etkinlik günlüklerine erişme başlıklı makalede özetlendiği şekilde etkinlik günlük kaydını destekler. Bu günlükler, İşleminiz içinde bildirim kalitesini test etmek ve korumak için yararlıdır.
Aşağıda, bir notificationLog
girişinin şeması bulunmaktadır:
Özellik | 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 üretime sunulmayan
İşlemler'de kullanılabilir.
Durumlara örnek olarak şunlar verilebilir:
Durum | Açıklama |
---|---|
EVENT_ID_MISSING |
Zorunlu eventId alanının eksik olduğunu gösterir.
|
PRIORITY_MISSING |
Bir priority alanının eksik olduğunu gösterir.
|
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
Bildirimde bulunan cihazın, SYNC içinde sağlanan notificationSupportedByAgent özelliğinin yanlış olduğunu belirtir.
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Kullanıcının GHA içindeki bildirim cihazında bildirimleri etkinleştirmediğini belirtir. Bu durum yalnızca üretime sunulmamış İşlemlerde kullanılabilir. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
Kullanıcının bildirim cihazını bir ev/yapıya atamadığını gösterir. Bu durum yalnızca üretime sunulmamış İşlemlerde kullanılabilir. |
Tüm bildirimler için geçerli olan bu genel durumların yanı sıra status
alanı, geçerli olduğu durumlarda özelliğe özgü durumlar da içerebilir (ör. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).