Akıllı ev işlemlerinin nasıl geliştirileceğini öğrenebileceğiniz yeni adres olan Google Home Geliştirici Merkezi'ne hoş geldiniz. Not: Actions Console'da işlem derlemeye devam edersiniz.

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

Bildirimler, smart home İşleminizin kullanıcılar ile cihaz hakkındaki önemli etkinlikler veya değişiklikler hakkında iletişim kurmak için Google Assistant kullanmasına olanak tanır. Kullanıcıları zamanında cihaz etkinlikleri (örneğin, kapıdayken) veya bir cihaz kilidi değişiminin başarıyla etkileşimde bulunması ya da sıkışması gibi istenen bir cihaz durumu değişikliği hakkında rapor oluşturmak için bildirimleri uygulayabilirsiniz.

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

  • Proaktif bildirimler: Cihazlarına kullanıcı isteği (ör. kapı zilinin çalması) olmadan kullanıcıyı bir smart home cihaz etkinliği hakkında uyarır.

  • Takip yanıtları: Bir cihaz komutu isteğinin başarılı veya başarısız olduğunun onaylanması (ör. bir kapıyı kilitlerken). 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 kullanıcılara akıllı hoparlörler ve akıllı ekranlarda duyuru olarak sunar. Proaktif bildirimler varsayılan olarak kapalıdır. Kullanıcılar, Google Home app (GHA)'ten gelen tüm proaktif bildirimleri etkinleştirebilir veya devre dışı bırakabilir.

Bildirimleri tetikleyen etkinlikler

Cihaz etkinlikleri gerçekleştiğinde, Sipariş karşılama siparişiniz 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 ekleyebileceğiniz verileri belirler.

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

Özellik Etkinlikler
Nesne Algılama Kapıda tanıdık 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 makinesi döngüsü tamamlandı."
SensorState Cihaz, desteklenen bir sensör durumu algılar. Örneğin: "Duman dedektörü duman algıladı."
Sıcaklık Kontrolü Cihaz bir sıcaklığa ayarlanıyor. Örneğin: "Fırın önceden 350 dereceye kadar ısıtıldı."
Ulusal Güçlendirme Sistem, giriş geri sayımıyla birlikte alarm öncesi bir duruma geçer ve açık bir kapıyla tetiklenir.
KameraCanlı Yayın Cihaz tarafından bir nesne veya hareket algılandıktan sonra kameranın canlı yayınına bağlantı verin.
MotionDetection "Hareket, 1 Temmuz 2020, 12:00'da algılandı."

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

Özellik Etkinlikler
Ulusal Güçlendirme action.devices.commands.ArmDisarm cihaz komutunun yürütülmesinin ardından tamamlanma durumu ve durum değişikliği. Örneğin: "Güvenlik sistemi etkinleştirildi."
Kilit Kilidi action.devices.commands.LockUnlock cihaz komutunun yürütülmesinin ardından tamamlanma durumu ve durum değişikliği. Örneğin: "Ön kapı kilitli" veya "Ön kapı sıkışmış."
Ağ Kontrolü 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 Kb/sn ve yükleme hızı 9,3 Kb/sn."
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ı."
Başlatma action.devices.commands.StartStop cihaz komutunun yürütülmesinin ardından 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 İşleminiz için bildirimler oluşturun

smart home İşlemlerinize şu 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 cihaz değişikliğini Google'a bildirmek için bir SYNC isteği gönderin.
  2. Bir bildirimi tetikleyen alakalı bir cihaz etkinliği veya durum değişikliği olduğunda Report State reportStateAndNotification API'sini çağırarak bildirim isteği gönderin. Cihaz durumu değiştiyse Report State ve Bildirim çağrılarınızda hem durum hem 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 belirtme

Kullanıcılar GHA uygulamasında bu özelliği etkinleştirerek proaktif bildirimler almak isteyip istemediklerini seçebilir. Dilerseniz smart home kullanıcısının uygulamasına, kullanıcıların bildirimleri cihaz üzerinden (ör. uygulama ayarlarından) açıkça değiştirmelerini de sağlayabilirsiniz.

Cihaz verilerini güncellemek için bir SYNC isteğinde bulunun çağrısı yaparak cihazınızda bildirimlerin etkinleştirildiğini 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 aşağıdaki güncellemelerden birini gönderin:

  • Kullanıcı, cihaz uygulamanızda bildirimleri açık bir şekilde açmışsa 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ın nasıl ayarlanacağına ilişkin bir örnek gösterilmektedir:

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

Google'a bildirim isteği gönderme

Assistant uygulamasında bildirimleri tetiklemek için karşılamanız, Report State ve Notification API çağrısı yoluyla Google Home Graph adresine bildirim yükü gönderir.

Google HomeGraph API'yi etkinleştirme

  1. Google Cloud Console içinde 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 üzerinden hizmet hesabı anahtarı oluşturmak için aşağıdaki talimatları uygulayın:

Not: Bu adımları gerçekleştirirken doğru GCP projesini kullandığınızdan emin olun. Bu proje, smart home proje kimliğinizle eşleşiyor.
  1. Google Cloud Console bölümünde Hizmet hesabı anahtarı oluştur sayfasına gidin.

    Hizmet Hesabı Anahtarı Oluştur sayfasına git
  2. Hizmet hesabı listesinden Yeni hizmet hesabı'nı seçin.
  3. Service account name (Hizmet hesabı adı) alanına bir ad girin.
  4. Service account ID (Hizmet hesabı kimliği) alanına bir kimlik girin.
  5. Rol listesinden Hizmet Hesapları > Hizmet Hesabı Jeton Oluşturucu'yu seçin.

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

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

Bildirimi gönder

devices.reportStateAndNotification API'yi kullanarak bildirim isteğinde bulunun. JSON isteğinizde, bildirimi tetikleyen etkinlik için platformunuz tarafından oluşturulan benzersiz bir kimlik olan bir eventId bulunmalıdır. eventId, her bildirim isteği gönderdiğinizde farklı olan rastgele bir kimlik olmalıdır.

API çağrınızda geçirdiğ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'ye çağrıda bulunmak için aşağıdaki yöntemlerden birini uygulayın:

Proaktif bildirim yükü gönderme

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

HTTP

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

  1. İndirilen hizmet hesabı JSON dosyasını kullanarak bir JSON Web Token (JWT) oluşturun. Daha fazla bilgi için Hizmet Hesabı Kullanarak Kimlik Doğrulama bölümüne bakın.
  2. oauth2l kullanarak https://www.googleapis.com/auth/homegraph kapsamıyla bir OAuth 2.0 erişim jetonu edinin:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. agentUserId ile JSON isteği oluşturun. Report State ve Bildirim için örnek bir JSON isteğ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 ve Bildirim JSON ile HTTP POST isteğinizdeki jetonu Google Home Graph uç noktasına kadar birleştirin. Aşağıda, test olarak curl öğesini 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 arabelleği hizmet tanımını alın.
  2. Desteklenen dillerden biri için istemci saplaması oluşturmak üzere gRPC geliştirici belgelerini 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. Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak google.homegraph hizmetini 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 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. 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();

// 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ı yükü, isteğin durumunu, varsa etkinlik hataları için hata kodlarını ve EXECUTE intent isteği sırasında sağlanan geçerli followUpToken değerini içerir. followUpToken öğesinin geçerli kalması ve yanıtı orijinal istekle doğru şekilde ilişkilendirmek için beş dakika içinde kullanılması gerekir.

Aşağıdaki snippet'te followUpToken alanı olan ö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 değerini sadece kullanıcının ilk olarak etkileşimde bulunduğu cihazda yayınlamak ve kullanıcının tüm cihazlarında yayınlamak için kullanır.

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

HTTP

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

  1. İndirilen hizmet hesabı JSON dosyasını kullanarak bir JSON Web Token (JWT) oluşturun. Daha fazla bilgi için Hizmet Hesabı Kullanarak Kimlik Doğrulama bölümüne bakın.
  2. oauth2l kullanarak https://www.googleapis.com/auth/homegraph kapsamıyla bir OAuth 2.0 erişim jetonu edinin:
  3. oauth2l fetch --credentials service-account.json \
      --scope https://www.googleapis.com/auth/homegraph
    
  4. agentUserId ile JSON isteği oluşturun. Report State ve Bildirim için örnek bir JSON isteğ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 ve Bildirim JSON ile HTTP POST isteğinizdeki jetonu Google Home Graph uç noktasına kadar birleştirin. Aşağıda, test olarak curl öğesini 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 arabelleği hizmet tanımını alın.
  2. Desteklenen dillerden biri için istemci saplaması oluşturmak üzere gRPC geliştirici belgelerini 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. Uygulama Varsayılan Kimlik Bilgileri'ni kullanarak google.homegraph hizmetini 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 için bağlamalar sağlar.

  1. Uygulama Varsayılan Kimlik Bilgilerini kullanarak HomeGraphApiService öğesini başlatın
  2. ReportStateAndNotificationRequest ile reportStateAndNotification yöntemini çağırın. 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 Logging ile olay günlüklerine erişme bölümünde belirtildiği şekilde olay günlük kaydını destekler. Bu günlükler, İşleminizde 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 belirtir.

status alanı, bildirim yükünde hatalara işaret edebilecek çeşitli durumları içerir. Bunlardan bazıları yalnızca üretimde kullanıma sunulmamış Action'larda kullanılabilir.

Örnekler:

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 Bildiren cihazın SYNC özelliğinde sağlanan notificationSupportedByAgent özelliğinin yanlış olduğunu belirtir.
NOTIFICATION_ENABLED_BY_USER_FALSE Kullanıcının, bildirim gönderen cihazda GHA içindeki bildirimleri etkinleştirmediğini gösterir. Bu durum yalnızca üretime sunulmamış İşlemler'de kullanılabilir.
NOTIFYING_DEVICE_NOT_IN_STRUCTURE Kullanıcının, bildirim yapan cihazı bir eve/yapıya atamadığını belirtir. Bu durum yalnızca üretime sunulmamış İşlemler'de kullanılabilir.

Tüm alanlara uygulanabilecek bu genel durumlara ek olarak status alanı, özelliğe (ör. OBJECT_DETECTION_DETECTION_TIMESTAMP_MISSING) göre özelliğe özgü durumları da içerebilir.