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

Bildirimler, smart home İşleminizin Google Assistant kullanarak kullanıcılarla cihazla ilgili önemli etkinlikler veya değişiklikler hakkında iletişim kurmasına olanak tanır. Cihaz etkinliklerine, örneğin birisi kapıya geldiğinde veya bir kapı kilidi sürgüsünün başarılı bir şekilde takılması ya da kilitlenmesi gibi istenen bir cihaz durum değişikliği hakkında rapor oluşturmak için bildirimleri kullanabilirsiniz.

smart home İşleminiz kullanıcılara aşağıdaki bildirim türlerini gönderebilir:

  • Proaktif bildirimler: Kullanıcıyı, cihazlarına önceden herhangi bir kullanıcı isteği (ör. kapı zilinin çalması) gerçekleştirmeden smart home cihaz etkinliğiyle ilgili olarak uyarır.

  • Takip yanıtları: Bir cihaz komutu isteğinin başarılı veya başarısız olduğunu (örneğin, bir kapıyı kilitlerken) onaylar. 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 akıllı hoparlörler 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, İşlem karşılama işleminiz 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 dahil edebileceğ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: "Ayşe ve Burak ön kapıda."
RunCycle Cihaz bir döngüyü tamamlar. Örneğin: "Çamaşır makinesinin döngüsü tamamlandı."
SensorState Cihaz desteklenen bir sensör durumu algıladı. Örneğin: "Duman dedektörü duman algıladı."
TemperatureControl Cihaz bir sıcaklık ayar noktasına ulaştı. Örneğin: "Fırın 350 dereceye önceden ısıtıldı."
ArmDisarm Sistem, açık bir kapının tetiklediği giriş geri sayımıyla alarm öncesi durumuna girer.
CameraStream Cihaz tarafından bir nesne veya hareket algılandığında kameranın canlı yayınına bağlantı oluşturun.
MotionDetection "Hareket 1 Temmuz 2020, saat 12:00'de algılandı."

Aşağıdaki özellikler takip yanıtlarını destekler:

Özellik Etkinlikler
ArmDisarm action.devices.commands.ArmDisarm cihaz komutunun yürütülmesinden sonra tamamlanma durumu ve durumu değişir. Örneğin: "Güvenlik sistemi etkinleştirildi."
LockUnlock action.devices.commands.LockUnlock cihaz komutunun yürütülmesinden sonra tamamlanma durumu ve durumu değişir. Örneğin: "Ön kapı kilitlendi" veya "Ön kapı sıkışmış."
NetworkControl action.devices.commands.TestNetworkSpeed cihaz komutunun yürütülmesinden sonra tamamlanma durumu ve durumu değişir. Örneğin: "Ağ hız testiniz tamamlandı. Ofis yönlendiricisindeki indirme hızı şu anda 80,2 Kb/sn, yükleme hızı ise 9,3 Kb/sn."
OpenClose action.devices.commands.OpenClose cihaz komutunun yürütülmesinden sonra tamamlanma durumu ve durumu değişir. Örneğin: "Ön kapı açıldı" veya "Ön kapı açılamadı."
StartStop action.devices.commands.StartStop cihaz komutunun yürütülmesinden sonra tamamlanma durumu ve durumu değişir. Ö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şturma

smart home İşleminize aşağıdaki aşamalarda bildirim ekleyin:

  1. 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ğini 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'yi ç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 etkin olup olmadığını belirtme

Kullanıcılar GHA uygulamasında bu özelliği etkinleştirerek proaktif bildirimler almak isteyip istemediklerini seçebilirler. smart home cihazınızın uygulamasında, isteğe bağlı olarak kullanıcıların, örneğin uygulama ayarlarınızdan, cihazdaki bildirimleri açık bir şekilde açıp kapatmalarına olanak tanıyabilirsiniz.

Cihaz verilerini güncellemek için bir Senkronizasyon İste çağrısı yaparak cihazınız için bildirimlerin etkin olduğunu 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 ş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 sunmadıysanız devices.notificationSupportedByAgent özelliğini true olarak ayarlayın.
  • Kullanıcı, cihaz uygulamanızda bildirimleri açık bir şekilde devre dışı bıraktıysa devices.notificationSupportedByAgent özelliğini false olarak ayarlayın.

Aşağıdaki snippet'te, SENKRONİZASYON yanıtınızı nasıl ayarlayacağınıza dair bir örnek gösterilmektedir:

devices: [{
   id: 'device123',
   ...
   notificationSupportedByAgent: true,
}]

Google'a bildirim istekleri gönder

Assistant'da bildirimlerin tetiklenmesi için, istek karşılama işleminiz bir Report State ve Notification API çağrısı aracılığıyla Google Home Graph cihazına bir bildirim yükü gönderir.

Google Home Graph API'yi etkinleştirin

  1. Google Cloud Console sayfasında HomeGraph API sayfasına gidin.

    Home Graph 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 uygulamasından bir hizmet hesabı anahtarı oluşturmak için şu 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 sayfasında Hizmet hesabı anahtarı oluştur sayfasına gidin.

    Hizmet Hesabı Anahtarı Oluşturun sayfasına gidin
  2. Hizmet hesabı listesinden Yeni hizmet hesabı'nı seçin.
  3. Hizmet hesabı adı alanına bir ad girin.
  4. Hizmet hesabı kimliği alanına bir kimlik girin.
  5. Rol listesinden Hizmet Hesapları > Hizmet Hesabı Jetonu Oluşturucu'yu seçin.

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

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

Bildirimi gönder

devices.reportStateAndNotification API'yi kullanarak bildirim isteği çağrısı 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önderme

API'yi çağırmak için şu sekmelerin birinden bir seçenek belirleyin:

HTTP

Home Graph API, bir HTTP uç noktası sağlar

  1. İ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.
  2. oauth2l kullanarak https://www.googleapis.com/auth/homegraph kapsamında bir OAuth 2.0 erişim jetonu alın:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. JSON isteğini agentUserId ile oluşturun. Report State ve Bildirim için JSON isteği örneği:
  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. Report State, Notification JSON ve jetonu, 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:
  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 bir gRPC uç noktası sağlar

  1. Home Graph API için protokol arabellek hizmeti tanımını alın.
  2. Desteklenen dillerden biri için istemci saplaması oluşturmak üzere gRPC geliştirici dokümanlarındaki talimatları uygulayın.
  3. 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.

  1. Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak google.homegraph hizmetini başlatın.
  2. reportStateAndNotification yöntemini ReportStateAndNotificationRequest ile çağırın. ReportStateAndNotificationResponse içeren bir Promise 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. Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak HomeGraphApiService hizmetini başlatın.
  2. ReportStateAndNotificationRequest ile reportStateAndNotification yöntemini çağırın. Bir 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);
    
Yanıt yükü gönderme

Bir takip yanıtının yükü, EXECUTE amaç isteği sırasında sağlanan isteğin durumunu, varsa etkinlik hatalarının hata kodlarını ve geçerli followUpToken değerini içerir. followUpToken, geçerli olarak kalmak ve yanıtı orijinal istekle düzgün bir şekilde ilişkilendirmek için beş dakika içinde kullanılmalıdır.

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, followUpToken bilgisini yalnızca kullanıcının başlangıçta etkileşimde bulunduğu cihazda oluşturmak ve kullanıcının tüm cihazlarında yayınlamamak için kullanır.

API'yi çağırmak için şu sekmelerin birinden bir seçenek belirleyin:

HTTP

Home Graph API, bir HTTP uç noktası sağlar

  1. İ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.
  2. oauth2l kullanarak https://www.googleapis.com/auth/homegraph kapsamında bir OAuth 2.0 erişim jetonu alın:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. JSON isteğini agentUserId ile oluşturun. Report State ve Bildirim için JSON isteği örneği:
  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. Report State, Notification JSON ve jetonu, 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:
  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 bir gRPC uç noktası sağlar

  1. Home Graph API için protokol arabellek hizmeti tanımını alın.
  2. Desteklenen dillerden biri için istemci saplaması oluşturmak üzere gRPC geliştirici dokümanlarındaki talimatları uygulayın.
  3. 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.

  1. Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak google.homegraph hizmetini başlatın.
  2. reportStateAndNotification yöntemini ReportStateAndNotificationRequest ile çağırın. ReportStateAndNotificationResponse içeren 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. Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak HomeGraphApiService hizmetini başlatın.
  2. ReportStateAndNotificationRequest ile reportStateAndNotification 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 olay günlüklerine erişme başlıklı makalede açıklandığı gibi olay günlük kaydını destekler. Bu günlükler, İşleminiz içindeki bildirimlerin kalitesini test etmek ve korumak için yararlıdır.

Aşağıda, bir notificationLog girişinin şeması verilmiştir:

Özellik 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 hatalara işaret edebilecek çeşitli durumlar içerir. Bunlardan bazıları yalnızca üretime sunulmamış işlemlerde kullanılabilir.

Örnek durumlar şunlardır:

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 SYNC içinde sağlanan, bildirimde bulunan cihazın 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ış işlemlerde kullanılabilir.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Kullanıcının bilgilendiren cihazı bir eve/yapıya atamadığını belirtir. Bu durum yalnızca üretime sunulmamış işlemlerde kullanılabilir.

status alanı, tüm bildirimler için geçerli olabilecek bu genel durumların yanı sıra, uygun olduğunda özelliğe özgü durumları da içerebilir (ör. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).