Akıllı ev İşlemleri için bildirimler

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:

  1. 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.
  2. 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ğini true olarak ayarlayın.
  • Kullanıcı, cihaz uygulamanızda bildirimleri açıkça devre dışı bıraktıysa devices.notificationSupportedByAgent özelliğini false 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

  1. Google Cloud Console bölümünde HomeGraph API sayfasına gidin.

    HomeGraph API sayfasına gidin
  2. smart home proje kimliğinizle eşleşen projeyi seçin.
  3. 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:

Not: Bu adımları uygularken doğru GCP projesini kullandığınızdan emin olun. Bu, smart home proje kimliğinizle eşleşen projedir.
  1. 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.

  2. Hizmet hesabı oluştur'u tıklayın.

  3. Hizmet hesabı adı alanına bir ad girin.

  4. Hizmet hesabı kimliği alanına bir kimlik girin.

  5. Hizmet hesabı açıklaması alanına bir açıklama girin.

  6. Oluştur ve devam et'i tıklayın.

  7. Rol açılır listesinden Hizmet Hesapları > Hizmet Hesabı OpenID Connect Kimlik Jetonu Oluşturucu'yu seçin.

  8. Devam'ı tıklayın.

  9. Bitti'yi tıklayın.

  10. Hizmet hesapları listesinden yeni oluşturduğunuz hizmet hesabını seçin ve İşlemler menüsünden Anahtarları yönet'i seçin.

  11. Anahtar ekle > Yeni anahtar oluştur'u seçin.

  12. Anahtar türü olarak JSON seçeneğini belirleyin.

  13. Oluştur'u tıklayın. Anahtarınızı içeren bir JSON dosyası bilgisayarınıza indirilir.

Hizmet hesabı anahtarları oluşturmayla ilgili ayrıntılı talimatlar ve bilgiler için Google Cloud Console Yardım sitesindeki Hizmet hesabı anahtarları oluşturma ve silme başlıklı makaleyi inceleyin.

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.

  1. 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.
  2. oauth2l kullanarak https://www.googleapis.com/auth/homegraph kapsamıyla bir OAuth 2.0 erişim jetonu alın:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. agentUserId ile JSON isteğini oluşturun. Report State ve Bildirim için örnek bir JSON isteğini burada bulabilirsiniz:
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
  6. 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:
  7. 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.

  1. Home Graph API'si için protocol buffers hizmet tanımını alın.
  2. Desteklenen dillerden birinde istemci saplamaları oluşturmak için gRPC geliştirici dokümanlarındaki adımları uygulayın.
  3. ReportStateAndNotification yöntemini çağırın.

Node.js

Google API'leri Node.js İstemcisi, Home Graph API'si için bağlamalar sağlar.

  1. google.homegraph hizmetini Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak başlatın.
  2. 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.

  1. HomeGraphApiService öğesini Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak başlatın.
  2. reportStateAndNotification yöntemini ReportStateAndNotificationRequest 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.

  1. 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.
  2. oauth2l kullanarak https://www.googleapis.com/auth/homegraph kapsamıyla bir OAuth 2.0 erişim jetonu alın:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. agentUserId ile JSON isteğini oluşturun. Report State ve Bildirim için örnek bir JSON isteğini burada bulabilirsiniz:
  5. {
      "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
                }
              }
            }
          }
        }
      }
    }
  6. 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:
  7. 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.

  1. Home Graph API'si için protocol buffers hizmet tanımını alın.
  2. Desteklenen dillerden birinde istemci saplamaları oluşturmak için gRPC geliştirici dokümanlarındaki adımları uygulayın.
  3. ReportStateAndNotification yöntemini çağırın.

Node.js

Google API'leri Node.js İstemcisi, Home Graph API'si için bağlamalar sağlar.

  1. google.homegraph hizmetini Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak başlatın.
  2. reportStateAndNotification yöntemini ReportStateAndNotificationRequest ile çağırın. ReportStateAndNotificationResponse ile bir Promise 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.

  1. HomeGraphApiService öğesini Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak başlatın.
  2. reportStateAndNotification yöntemini ReportStateAndNotificationRequest 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).