Bildirimler, Cloud-to-cloud entegrasyonunuzun Google Assistant kullanarak kullanıcılarla önemli cihazla ilgili etkinlikler veya değişiklikler hakkında iletişim kurmasına olanak tanır. Kullanıcıları zamanında cihaz etkinlikleri konusunda uyarmak için bildirimler uygulayabilirsiniz. Örneğin, kapıda biri olduğunda veya istenen cihaz durumu değişikliği hakkında rapor vermek için (ör. kapı kilidi sürgüsü başarıyla takıldığında veya sıkıştığında) bildirimler uygulayabilirsiniz.
Cloud-to-cloud entegrasyonunuz, kullanıcılara aşağıdaki bildirim türlerini gönderebilir:
Proaktif bildirimler: Kullanıcıyı, cihazlarına önceden herhangi bir istekte bulunmadan smart home cihaz etkinliği konusunda uyarır. Örneğin, kapı zili çaldığında bildirim gönderir.
Takip yanıtları: Bir cihaz komut isteğinin başarılı veya başarısız olduğuna dair onay (ör. kapı kilitlenirken). Tamamlanması zaman alan cihaz komutları için bu uyarıları kullanın. Ek 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örlerde ve akıllı ekranlarda duyuru olarak sunar. Proaktif bildirimler varsayılan olarak devre dışıdır. Kullanıcılar, Google Home app (GHA) simgesine dokunarak tüm proaktif bildirimleri etkinleştirebilir veya devre dışı bırakabilir.
Bildirimleri tetikleyen etkinlikler
Cihaz etkinlikleri gerçekleştiğinde karşılamanız Google'a bir bildirim isteği gönderir. Cloud-to-cloud entegrasyonunuzun desteklediği cihaz özellikleri, hangi tür bildirim etkinliklerinin kullanılabileceğini ve bu bildirimlere hangi verileri ekleyebileceğinizi belirler.
Aşağıdaki özellikler proaktif bildirimleri destekler:
Özellik | Etkinlikler |
---|---|
ObjectDetection | Cihaz tarafından algılanan nesneler (ör. kapıda tanınan bir yüz algılandığında) Örneğin: "Aylin ve Bora ön kapıda." |
RunCycle | Cihaz bir döngüyü tamamladığında Örneğin: "Çamaşır makinesi döngüsü tamamlandı." |
SensorState | Cihaz, desteklenen bir sensör durumu algıladığında Örneğin: "Duman dedektörü duman algıladı." |
Aşağıdaki özellikler takip yanıtlarını destekler:
Özellik | Etkinlikler |
---|---|
LockUnlock | action.devices.commands.LockUnlock cihaz komutunun yürütülmesinin ardından tamamlanma durumu ve durum değişikliği. Örneğin: "Ön kapı kilitlendi" veya "Ön kapı sıkıştı."
|
NetworkControl | 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 Kbps, yükleme hızı ise 9,3 Kbps."
|
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ı."
|
Tüm cihaz türleri, geçerli özelliklerle ilgili bildirimleri destekler.
Buluttan buluta entegrasyonunuz için bildirimler oluşturma
Cloud-to-cloud entegrasyonunuza aşağıdaki aşamalarda bildirim ekleyin:
- smart home cihaz uygulamanızda bildirimlerin etkin olup olmadığını 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. - Bildirimi tetikleyen alakalı bir cihaz etkinliği veya durum değişikliği gerçekleştiğinde Report State
reportStateAndNotification
API'sini çağırarak bir 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ü gönderebilirsiniz.
Aşağıdaki bölümlerde bu adımlar daha ayrıntılı olarak ele alınmaktadır.
Uygulamanızda bildirimlerin etkin olup olmadığını belirtin
Kullanıcılar, GHA bölümünde bu özelliği etkinleştirerek proaktif bildirimler almayı tercih edebilir. smart home cihazınızın uygulamasında, kullanıcıların bildirimleri cihazdan (ör. uygulama ayarlarınızdan) açıkça etkinleştirmesine veya devre dışı bırakmasına olanak tanıyan bir özellik de ekleyebilirsiniz.
Google Home uygulaması bildirimlerinizi yönetme başlıklı makaleyi inceleyin.Cihaz verilerini güncellemek için SYNC isteği çağrısı yaparak Google'a cihazınızda bildirimlerin etkinleştirildiğini bildirin. Kullanıcılar bu ayarı uygulamanızda her değiştirdiğinde SYNC
gibi bir istek 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 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ı nasıl ayarlayacağınıza dair bir örnek gösterilmektedir:
devices: [{
id: 'device123',
...
notificationSupportedByAgent: true,
}]
Google'a bildirim istekleri gönderme
Assistant üzerinde bildirimleri tetiklemek için Google Home Graph, Report State ve Notification API çağrısı aracılığıyla Google Home Graph'ye bir bildirim yükü gönderir.
Google HomeGraph API'yi etkinleştirme
-
Google Cloud Console bölümünde 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'dan hizmet hesabı anahtarı oluşturmak için aşağıdaki talimatları uygulayın:
-
Google Cloud Console bölümünde Hizmet hesapları sayfasına gidin.
Hizmet hesapları sayfasına gidin.Hizmet Hesapları sayfasına yönlendirilmeden önce bir proje seçmeniz gerekebilir.
Hizmet hesabı oluştur'u tıklayın.
Hizmet hesabı adı alanına bir ad girin.
Hizmet hesabı kimliği alanına bir kimlik girin.
Hizmet hesabı açıklaması alanına bir açıklama girin.
Oluştur ve devam et'i tıklayın.
Rol açılır listesinden Hizmet Hesapları > Hizmet Hesabı OpenID Connect Kimlik Jetonu Oluşturucu'yu seçin.
Devam'ı tıklayın.
Bitti'yi tıklayın.
Hizmet hesapları listesinden yeni oluşturduğunuz hizmet hesabını seçin ve
İşlemler menüsünden Anahtarları yönet'i seçin.Anahtar ekle > Yeni anahtar oluştur'u 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önderin.
devices.reportStateAndNotification
API'yi kullanarak bildirim isteği çağrısı yapın.
JSON isteğiniz, bildirimi tetikleyen etkinlik için platformunuz tarafından oluşturulan benzersiz bir kimlik olan eventId
içermelidir. eventId
, bildirim isteği gönderdiğiniz her seferinde farklı olan rastgele bir kimlik olmalıdır.
API çağrınızda ilettiğiniz notifications
nesnesine, bildirimin nasıl sunulacağını 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önderme
API'yi çağırmak için şu sekmelerden birinde bir seçenek belirleyin:
HTTP
Home Graph API'si bir HTTP uç noktası sağlar.
- JSON Web Token (JWT) oluşturmak için indirilen hizmet hesabı JSON dosyasını kullanın. Daha fazla bilgi için Hizmet Hesabı Kullanarak Kimlik Doğrulama başlıklı makaleyi inceleyin.
- 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. Report State ve Bildirim için örnek bir JSON isteğini burada bulabilirsiniz:- Google Home Graph uç noktasına yönelik HTTP POST isteğinizde Report State ve Notification JSON'u ile jetonu birleştirin. Aşağıda, test olarak
curl
kullanarak komut satırında isteğin nasıl yapılacağı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'si bir gRPC uç noktası sağlar.
- Home Graph API'si için protocol buffers hizmet tanımını alın.
- Desteklenen dillerden birinde istemci saplamaları oluşturmak için gRPC geliştirici dokümanlarındaki adımları 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.
google.homegraph
hizmetini Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak başlatın.-
reportStateAndNotification
yöntemini ReportStateAndNotificationRequest ile çağırın.Promise
ile ReportStateAndNotificationResponse 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'si için bağlamalar sağlar.
-
HomeGraphApiService
öğesini Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak başlatın. -
reportStateAndNotification
yönteminiReportStateAndNotificationRequest
ile ç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ünde, isteğin durumu, varsa etkinlik hatalarıyla ilgili hata kodları ve EXECUTE
amaç isteği sırasında sağlanan geçerli followUpToken
bulunur. followUpToken
, geçerliliğini korumak ve yanıtı orijinal istekle doğru şekilde ilişkilendirmek için beş dakika içinde kullanılmalıdır.
Aşağıdaki snippet'te, followUpToken
alanı içeren bir örnek 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, bildirimi yalnızca kullanıcının ilk etkileşimde bulunduğu cihazda göstermek ve kullanıcının tüm cihazlarında yayınlamamak için followUpToken
kullanır.
API'yi çağırmak için şu sekmelerden birinde bir seçenek belirleyin:
HTTP
Home Graph API'si bir HTTP uç noktası sağlar.
- JSON Web Token (JWT) oluşturmak için indirilen hizmet hesabı JSON dosyasını kullanın. Daha fazla bilgi için Hizmet Hesabı Kullanarak Kimlik Doğrulama başlıklı makaleyi inceleyin.
- 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. Report State ve Bildirim için örnek bir JSON isteğini burada bulabilirsiniz:- Google Home Graph uç noktasına yönelik HTTP POST isteğinizde Report State ve Notification JSON'u ile jetonu birleştirin. Aşağıda, test olarak
curl
kullanarak komut satırında isteğin nasıl yapılacağı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'si bir gRPC uç noktası sağlar.
- Home Graph API'si için protocol buffers hizmet tanımını alın.
- Desteklenen dillerden birinde istemci saplamaları oluşturmak için gRPC geliştirici dokümanlarındaki adımları 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.
google.homegraph
hizmetini Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak başlatın.-
reportStateAndNotification
yöntemini ReportStateAndNotificationRequest ile ç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'si için bağlamalar sağlar.
-
HomeGraphApiService
öğesini Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak başlatın. -
reportStateAndNotification
yönteminiReportStateAndNotificationRequest
ile çağırın. Bu işlev,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'dan Cloud'a için Cloud Logging bölümünde belirtildiği gibi etkinlik günlüğünü destekler. Bu günlükler, işleminizdeki bildirim kalitesini test etmek ve korumak için yararlı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 gösterir. |
status
alanı, bildirim yükünde hatalar olabileceğini gösteren çeşitli durumları içerir. Bunlardan bazıları yalnızca üretime sunulmamış işlemler için geçerli olabilir.
Örnek durumlar:
Durum | Açıklama |
---|---|
EVENT_ID_MISSING |
Zorunlu eventId alanının eksik olduğunu gösterir.
|
PRIORITY_MISSING |
priority alanının eksik olduğunu gösterir.
|
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE |
Bildirim gönderen cihazın notificationSupportedByAgent özelliğinin SYNC içinde sağlanan değerinin yanlış olduğunu gösterir.
|
NOTIFICATION_ENABLED_BY_USER_FALSE |
Kullanıcının, GHA bölümünde bildirim gönderen cihazda bildirimleri etkinleştirmediğini gösterir. Bu durum yalnızca üretime sunulmamış entegrasyonlarda kullanılabilir. |
NOTIFYING_DEVICE_NOT_IN_STRUCTURE |
Kullanıcının, bildirim gönderen cihazı bir eve/yapıya atamadığını gösterir. Bu durum yalnızca üretimde kullanıma sunulmamış entegrasyonlarda kullanılabilir. |
Tüm bildirimler için geçerli olabilecek bu genel durumların yanı sıra, status
alanı uygun durumlarda özelliğe özgü durumları da içerebilir (ör. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING
).