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

Bildirimler, Cloud-to-cloud entegrasyonunuzun cihazla ilgili önemli etkinlikler veya değişiklikler hakkında kullanıcılarla iletişim kurmak için Google Assistant kullanmasına olanak tanır. Kullanıcıları cihazla ilgili zamanında gerçekleşen etkinlikler (ör. kapıda biri olduğunda) konusunda uyarmak veya istenen bir cihaz durumu değişikliğini (ör. kapı kilidi pimi başarıyla etkinleştirildiğinde veya sıkıştığında) bildirmek için bildirimler uygulayabilirsiniz.

Cloud-to-cloud entegrasyonunuz kullanıcılara aşağıdaki türde bildirimler gönderebilir:

  • Proaktif bildirimler: Kullanıcının cihazında herhangi bir istek olmadan (ör. kapı zili çaldığında) smart homecihaz etkinliği hakkında kullanıcıyı uyarır.

  • İzleme yanıtları: Bir cihaz komut isteği (ör. kapı kilitlendiğinde) başarılı veya başarısız olduğunun onayıdır. 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örler ve akıllı ekranlarda duyuru olarak kullanıcılara sunar. Proaktif bildirimler varsayılan olarak devre dışıdır. Kullanıcılar, Google Home app (GHA) bölümünden tüm proaktif bildirimleri etkinleştirebilir veya devre dışı bırakabilir.

Bildirimleri tetikleyen etkinlikler

Cihaz etkinlikleri gerçekleştiğinde, sipariş tamamlama hizmetiniz Google'a bir bildirim isteği gönderir. Cloud-to-cloud entegrasyonunuzun desteklediği cihaz özellikleri, kullanılabilen bildirim etkinliği türlerini ve bu bildirimlere dahil edebileceğiniz verileri belirler.

Aşağıdaki özellikler proaktif bildirimleri destekler:

Özellik Etkinlikler
ObjectDetection Cihaz tarafından algılanan nesneler (ör. tanınan bir yüz kapıda algılandığında). Örneğin: "Aylin ve Bora ö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 durumunu algılar. Ö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ülmesinden 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 komutunun yürütülmesinden 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 komutunun yürütülmesinden sonra 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 bildirim oluşturma

Cloud-to-cloud entegrasyonunuza aşağıdaki aşamalarda bildirim ekleyin:

  1. Bildirimlerin smart home cihaz uygulamanızda etkin olup olmadığını Google'a bildirin. Kullanıcılar uygulamanızda bildirimleri etkinleştirirse veya devre dışı bırakırsa Google'ı cihaz değişikliği hakkında bilgilendirmek 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 Notification ç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ı belirtme

Kullanıcılar, GHA'te bu özelliği etkinleştirerek proaktif bildirim almak isteyip istemediklerini seçebilir. smart home cihazınızın uygulamasında, kullanıcıların bildirimleri cihazdan (ör. uygulama ayarlarınızdan) açıkça değiştirebilme özelliğini isteğe bağlı olarak da ekleyebilirsiniz.

Cihaz verilerini güncellemek için SYNC iste çağrısı yaparak Google'a cihazınızda bildirimlerin etkin olduğunu belirtin. Kullanıcılar uygulamanızda bu ayarı değiştirdiğinde bu gibi 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ça etkinleştirdiyse veya açma/kapatma seçeneği sunmadıysanız devices.notificationSupportedByAgent mülkünü true olarak ayarlayın.
  • Kullanıcı, cihaz uygulamanızda bildirimleri açıkça devre dışı bıraktıysa devices.notificationSupportedByAgent mülkünü 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'te bildirimleri tetiklemek için sipariş tamamlama işleminiz, Report State ve Notification API çağrısı aracılığıyla Google Home Graph'e bir bildirim yükü gönderir.

Google HomeGraph API'yi etkinleştirme

  1. Google Cloud Console sayfasında 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'ten 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'te Hizmet hesabı anahtarı oluştur sayfasına gidin.

    Hizmet Hesabı Anahtarı Oluştur 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 listesinde Hizmet Hesapları > Hizmet Hesabı Jetonu Oluşturucusu'nu seçin.

  6. Anahtar türü için 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önderme

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ükleyiciyi 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 aşağıdaki sekmelerden birini seçin:

HTTP

Home Graph API, 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ına sahip bir OAuth 2.0 erişim jetonu edinin:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. agentUserId ile JSON isteğini oluşturun. Report State ve Notification için örnek bir JSON isteği:
    4. {
  "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
            }
          }
        }
      }
    }
  }
}
  4. Report State ve Notification JSON'u ve Google Home Graph uç noktasına gönderdiğiniz HTTP POST isteğinde jetonu birleştirin. Aşağıda, test amacıyla curl kullanarak komut satırında isteği nasıl yapacağınıza dair bir örnek verilmiştir:
    5. 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 için protokol arabellekleri hizmet tanımını alın.
  2. Desteklenen dillerden biri için istemci saplamaları oluşturmak üzere gRPC geliştirici dokümanlarını uygulayın.
  3. ReportStateAndNotification yöntemini çağırın.

Node.js

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

  1. google.homegraph hizmetini Uygulama Varsayılan Kimlik Bilgileri ile başlatın.
  2. ReportStateAndNotificationRequest ile reportStateAndNotification yöntemini çağırın. ReportStateAndNotificationResponse ile 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 dosyasını 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);
Takip yanıtı yükü gönderme

Bir takip yanıtının yükü, isteğin durumunu, varsa etkinlik hatalarıyla ilgili hata kodlarını ve EXECUTE intent isteği sırasında sağlanan geçerli followUpToken değerini içerir. followUpToken, geçerliliğini korumak ve yanıtın orijinal istekle doğru şekilde ilişkilendirilmesi 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, bildirimi yalnızca kullanıcının başlangıçta etkileşimde bulunduğu cihazda yayınlamak için followUpToken değerini kullanır ve kullanıcının tüm cihazlarında yayınlamaz.

API'yi çağırmak için aşağıdaki sekmelerden birini seçin:

HTTP

Home Graph API, 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ına sahip bir OAuth 2.0 erişim jetonu edinin:
    3. oauth2l fetch --credentials service-account.json \
  --scope https://www.googleapis.com/auth/homegraph
  3. agentUserId ile JSON isteğini oluşturun. Report State ve Notification için örnek bir JSON isteği:
    4. {
  "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
            }
          }
        }
      }
    }
  }
}
  4. Report State ve Notification JSON'u ve Google Home Graph uç noktasına gönderdiğiniz HTTP POST isteğinde jetonu birleştirin. Aşağıda, test amacıyla curl kullanarak komut satırında isteği nasıl yapacağınıza dair bir örnek verilmiştir:
    5. 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 için protokol arabellekleri hizmet tanımını alın.
  2. Desteklenen dillerden biri için istemci saplamaları oluşturmak üzere gRPC geliştirici dokümanlarını takip edin.
  3. ReportStateAndNotification yöntemini çağırın.

Node.js

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

  1. google.homegraph hizmetini Uygulama Varsayılan Kimlik Bilgileri ile başlatın.
  2. ReportStateAndNotificationRequest ile reportStateAndNotification yöntemini ç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. Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak HomeGraphApiService'i başlatın
  2. ReportStateAndNotificationRequest ile reportStateAndNotification yöntemini çağırın. Bir değer döndürür ReportStateAndNotificationResponse
// 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, Buluttan buluta Cloud Logging bölümünde açıklandığı gibi etkinlik günlüğünü destekler. Bu günlükler, işleminizdeki 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 gösterir.

status alanı, bildirim yükündeki hataları gösterebilecek ç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 gösterir.
PRIORITY_MISSING priority alanının eksik olduğunu gösterir.
NOTIFICATION_SUPPORTED_BY_AGENT_FALSE Bildiren cihazın SYNC özelliğinin SYNC değerinde yanlış olduğunu gösterir.notificationSupportedByAgent
NOTIFICATION_ENABLED_BY_USER_FALSE Kullanıcının, GHA'te bildiren cihazda bildirimleri etkinleştirmediğini belirtir. Bu durum yalnızca üretime sunulmamış entegrasyonların
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Kullanıcının, bildirim cihazını bir eve/yapıya atamadığını belirtir. Bu durum yalnızca üretime sunulmamış entegrasyonların

Tüm bildirimler için geçerli olabilecek bu genel durumlara ek olarak status alanı, geçerli olduğu durumlarda özelliğe özgü durumları da içerebilir (ör. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING).

Önceki
Rapor Durumunu Uygulama
Sonraki
Buluttan buluta entegrasyonu test etme