Etkinlikler

Etkinlikler eşzamansız olup Google Cloud Pub/Sub tarafından yönetilir ve her Projectiçin tek bir konu kullanılır. Etkinlikler tüm cihazlar ve yapılar için güncellemeler sağlar. Erişim jetonu kullanıcı tarafından iptal edilmediği ve etkinlik mesajlarının süresi dolmadığı sürece etkinliklerin alınması garanti edilir.

Etkinlikleri etkinleştir

Etkinlikler, SDM API'nin isteğe bağlı bir özelliğidir. Etkinlikleri etkinleştirme bölümünü inceleyerek bunları nasıl etkinleştireceğinizi öğrenin Project.

Google Cloud Pub/Sub

Pub/Sub'ın işleyiş şekli hakkında daha fazla bilgi edinmek için Google Cloud Pub/Sub belgelerine bakın. Özellikle:

Etkinlik aboneliği

Ocak 2025'ten önce, Projectiçin etkinlikler etkinleştirilmişse size şu biçimlerde Project kimliğine özel bir konu sağlanıyordu:

projects/gcp-project-name/subscriptions/topic-id
 Ocak 2025'ten sonra oluşturulan projelerin Pub/Sub konularını kendileri barındırması gerekir ve kendi konu kimliğinizi sağlamanız gerekir. Daha fazla bilgi için Konu oluşturma başlıklı makaleyi inceleyin.

Etkinlik almak için kullanım alanınıza bağlı olarak söz konusu konuda çekme veya push aboneliği oluşturun. SDM konusuna birden fazla abonelik desteklenir. Daha fazla bilgi için Abonelikleri yönetme başlıklı makaleyi inceleyin.

Başlatma etkinlikleri

Pub/Sub aboneliği oluşturulduktan sonra etkinlikleri ilk kez başlatmak için tek seferlik tetikleyici olarak devices.list API çağrısı yapın. Bu çağrıdan sonra tüm yapılar ve cihazlar için etkinlikler yayınlanır.

Örnek için Hızlı Başlangıç Kılavuzu'ndaki Yetkilendirme sayfasına bakın.

Etkinlik sırası

Pub/Sub, etkinliklerin sıralı olarak teslim edilmesini garanti etmez ve etkinliklerin alınma sırası, etkinliklerin gerçekleşme sırasıyla eşleşmeyebilir. Etkinlik sırasının mutabakatına yardımcı olması için timestamp alanını kullanın. Etkinlikler ayrı ayrı veya tek bir etkinlik mesajında birleştirilmiş olarak da gelebilir.

Daha fazla bilgi için İletileri sıralama başlıklı makaleyi inceleyin.

User ID'ler

Uygulamanız kullanıcılar (yapı veya cihaz yerine) üzerine kuruluysa kaynakları ve etkinlikleri ilişkilendirmek için etkinlik yükündeki userID alanını kullanın. Bu alan, belirli bir kullanıcıyı temsil eden karartılmış bir kimliktir.

userID, her API çağrısının HTTP yanıt başlığında da bulunur.

İlişki etkinlikleri

İlişki etkinlikleri, bir kaynağın ilişkisel güncellemesini temsil eder. Örneğin, bir cihaz bir yapıya eklendiğinde veya bir yapıdan silindiğinde.

Üç tür ilişki etkinliği vardır:

  • OLUŞTURULDU
  • SİLİNDİ
  • GÜNCELLENDİ

İlişki etkinliğinin yükü aşağıdaki gibidir:

Yük

{
  "eventId" : "81688b62-4f69-432f-bbe0-5270032f5466",
  "timestamp" : "2019-01-01T00:00:01Z",
  "relationUpdate" : {
    "type" : "CREATED",
    "subject" : "enterprises/project-id/structures/structure-id",
    "object" : "enterprises/project-id/devices/device-id"
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
}

İlişki etkinliğinde object, etkinliği tetikleyen kaynak, subject ise object ile ilişki kurulan kaynaktır. Yukarıdaki örnekte, bir user , bu cihaza erişim izni vermiş ve user'nin yetkili cihazı artık yetkili yapısıyla ilişkilendirilmiş, bu da etkinliği tetiklemiştir. developer

subject yalnızca bir oda veya yapı olabilir. a developer , useryapısını görüntüleme iznine sahip değilse subject her zaman boş olur.

Alanlar

Alan Açıklama Veri Türü
eventId Etkinliğin benzersiz tanımlayıcısı. string
Örnek: "4ec221c5-4cbc-4fd5-ae2e-6eebd1311876"
timestamp Etkinliğin gerçekleştiği zaman. string
Örnek: "2019-01-01T00:00:01Z"
relationUpdate İlişki güncellemesiyle ilgili bilgileri ayrıntılı olarak açıklayan bir nesne. object
userId Kullanıcıyı temsil eden benzersiz ve karartılmış tanımlayıcı. string
Örnek: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"

Farklı etkinlik türleri ve bunların işleyiş şekli hakkında daha fazla bilgi için Etkinlikler başlıklı makaleyi inceleyin.

Örnekler

Etkinlik yükleri, her ilişki etkinliği türü için farklıdır:

OLUŞTURULMA ZAMANI:

Yapı oluşturuldu

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

Cihaz oluşturuldu

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

Cihaz oluşturuldu

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

GÜNCELLENDİ

Cihaz taşındı

"relationUpdate" : {
  "type" : "UPDATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

SİLİNDİ

Yapı silindi

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

Cihaz silindi

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

Cihaz silindi

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

İlişki etkinlikleri şu durumlarda gönderilmez:

  • Bir oda silindiğinde

Kaynak etkinlikleri

Kaynak etkinliği, kaynağa özgü bir güncellemeyi temsil eder. Özellik alanının değerindeki bir değişikliğe (ör. termostatın modunu değiştirme) yanıt olarak gönderilebilir. Ayrıca, bir cihaz düğmesine basma gibi bir özellik alanını değiştirmeyen bir cihaz işlemini de temsil edebilir.

Özellik alanının değerindeki bir değişikliğe yanıt olarak oluşturulan etkinlik, cihaz GET çağrısına benzer şekilde bir traits nesnesi içerir:

Yük

{
  "eventId" : "b5a3cb32-3ca8-4b0b-9510-c6a9e70f00f4",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.ThermostatMode" : {
        "mode" : "COOL"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Herhangi bir özellik alanı değişikliği kaynağı etkinliğinin yük biçimini anlamak için bireysel özellik dokümanlarını kullanın.

Bir özellik alanını değiştirmeyen bir cihaz işlemine yanıt olarak oluşturulan etkinlikte de resourceUpdate nesnesi içeren bir yük bulunur ancak traits nesnesi yerine events nesnesi bulunur:

Yük

{
  "eventId" : "803821e5-2626-41d5-8ea2-04b6fdb88f8c",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "HEQiFiTuneH7NJVZ-kHxnbZyU9...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Bu tür kaynak etkinlikleri belirli özelliklerde tanımlanır. Örneğin, hareket etkinliği CameraMotion özelliğinde tanımlanır. Bu tür kaynak etkinliklerinin yük biçimini anlamak için her özelliğin dokümanlarına bakın.

Alanlar

Alan Açıklama Veri Türü
eventId Etkinliğin benzersiz tanımlayıcısı. string
Örnek: "803821e5-2626-41d5-8ea2-04b6fdb88f8c"
timestamp Etkinliğin gerçekleştiği zaman. string
Örnek: "2019-01-01T00:00:01Z"
resourceUpdate Kaynak güncellemesiyle ilgili bilgileri ayrıntılı olarak açıklayan bir nesne. object
userId Kullanıcıyı temsil eden benzersiz ve karartılmış tanımlayıcı. string
Örnek: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
eventThreadId Etkinlik iş parçacığının benzersiz tanımlayıcısı. string
Örnek: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
eventThreadState Etkinlik iş parçacığının durumu. string
Değerler: "BAŞLADI", "GÜNCELLENDİ", "SONA ERDİ"
resourceGroup Bu etkinlikle benzer güncellemeleri olabilecek kaynakları gösteren bir nesne. Etkinliğin kaynağı (resourceUpdate nesnesinden) bu nesnede her zaman bulunur. object

Farklı etkinlik türleri ve bunların işleyiş şekli hakkında daha fazla bilgi için Etkinlikler başlıklı makaleyi inceleyin.

Güncellenebilir bildirimler

Kaynak etkinliklerine dayalı bildirimler, Android veya iOS gibi bir uygulamada uygulanabilir. Gönderilen bildirim sayısını azaltmak için güncellenebilir bildirimler adlı bir özellik uygulanabilir. Bu özellik sayesinde, aynı etkinlik iş parçacığındaki sonraki etkinliklere göre mevcut bildirimler yeni bilgilerle güncellenir.

Güncellenebilir bildirimleri destekleyen etkinlikler seçin ve dokümanlarda Güncellenebilir  olarak etiketleyin. Bu etkinliklerin yüklerinde eventThreadId adlı ek bir alan bulunur. Bu alanı, kullanıcıya gösterilen mevcut bir bildirimi güncellemek amacıyla ayrı etkinlikleri birbirine bağlamak için kullanın.

Etkinlik iş parçacığı, etkinlik oturumuyla aynı değildir. Etkinlik iş parçacığı, aynı iş parçacığındaki önceki bir etkinliğin güncellenen durumunu tanımlar. Etkinlik oturumu, birbiriyle ilişkili ayrı etkinlikleri tanımlar ve belirli bir etkinlik oturumu için birden fazla etkinlik iş parçacığı olabilir.

Farklı etkinlik türleri, bildirim amacıyla farklı ileti dizilerinde gruplandırılır.

Bu ileti gruplandırma ve zamanlama mantığı Google tarafından yönetilir ve herhangi bir zamanda değişebilir. A developer , SDM API tarafından sağlanan etkinlik iş parçacıklarına ve oturumlara göre bildirimleri güncellemelidir.

İleti dizisi durumu

Güncellenebilir bildirimleri destekleyen etkinliklerde, etkinlik ileti dizisinin o anki durumunu gösteren bir eventThreadState alanı da bulunur. Bu alan aşağıdaki değerlere sahiptir:

  • BAŞLATILDI: Etkinlik dizisindeki ilk etkinlik.
  • GÜNCELLENDİ: Devam eden bir etkinlik iş parçacığındaki etkinlik. Tek bir iş parçacığında bu durumda sıfır veya daha fazla etkinlik olabilir.
  • SONLANDIRILDI: Etkinlik dizisindeki son etkinliktir. Dizi türüne bağlı olarak, son GÜNCELLENDİ etkinliğinin bir kopyası olabilir.

Bu alan, bir etkinlik iş parçacığının ilerleme durumunu ve ne zaman sona erdiğini izlemek için kullanılabilir.

Etkinlik filtreleme

Bazı durumlarda, bir cihaz tarafından algılanan etkinlikler, SDM Pub/Sub konusuna yayınlanmaktan filtrelenebilir. Bu davranışa etkinlik filtreleme adı verilir. Etkinlik filtrelemenin amacı, kısa süre içinde çok fazla benzer etkinlik mesajı yayınlamayı önlemektir.

Örneğin, ilk hareket etkinliği için bir SDM konusuna mesaj yayınlanabilir. Bundan sonra Motion ile ilgili diğer mesajlar, belirli bir süre geçene kadar yayınlanmaktan filtrelenir. Bu süre geçtikten sonra, söz konusu etkinlik türü için etkinlik mesajı tekrar yayınlanabilir.

Google Home uygulamasında (GHA) filtrelenen etkinlikler, user'nın etkinlik geçmişinde gösterilmeye devam eder. Ancak bu tür etkinlikler, bildirim türü etkinleştirilmiş olsa bile uygulama bildirimi oluşturmaz.

Her etkinlik türünün, Google tarafından tanımlanan ve herhangi bir zamanda değiştirilebilen kendi etkinlik filtreleme mantığı vardır. Bu etkinlik filtreleme mantığı, etkinlik iş parçacığı ve oturum mantığından bağımsızdır.

Hizmet hesapları

SDM API aboneliklerini ve etkinlik mesajlarını yönetmek için hizmet hesapları önerilir. Hizmet hesabı, bir kişi tarafından değil bir uygulama veya sanal makine tarafından kullanılır ve kendine ait benzersiz bir hesap anahtarı vardır.

Pub/Sub API için hizmet hesabı yetkilendirmesi, iki aşamalı OAuth (2LO) kullanır.

2LO yetkilendirme akışında:

  • developer , hizmet anahtarı kullanarak erişim jetonu ister.
  • developer , API'ye yapılan çağrılarda erişim jetonunu kullanır.

Google 2LO ve kurulum hakkında daha fazla bilgi edinmek için Sunucudan Sunucuya Uygulamalar için OAuth 2.0'ı Kullanma başlıklı makaleyi inceleyin.

Yetkilendirme

Hizmet hesabı, Pub/Sub API ile kullanılmak üzere yetkilendirilmelidir:

  1. Google Cloud'da Cloud Pub/Sub API'yi etkinleştirin.
  2. Hizmet hesabı oluşturma bölümünde açıklandığı gibi bir hizmet hesabı ve hizmet hesabı anahtarı oluşturun. Yalnızca Pub/Sub Abonesi rolünü vermenizi öneririz. Pub/Sub API'yi kullanacak makineye hizmet hesabı anahtarını indirdiğinizden emin olun.
  3. Önceki adımda yer alan sayfadaki talimatları uygulayarak kimlik doğrulama kimlik bilgilerinizi (hizmet hesabı anahtarı) uygulama kodunuza sağlayın veya API erişimini hızlı bir şekilde test etmek istiyorsanız oauth2l'ı kullanarak erişim jetonunu manuel olarak alın.
  4. İletileri çekmek ve onaylamak için Pub/Sub project.subscriptions API ile hizmet hesabı kimlik bilgilerini veya erişim jetonunu kullanın.

oauth2l

Google oauth2l, Go ile yazılmış bir OAuth komut satırı aracıdır. Mac veya Linux için Go'yu kullanarak yükleyin.

  1. Sisteminizde Go yoksa önce indirip yükleyin.
  2. Go yüklendikten sonra oauth2l yükleyin ve konumunu PATH ortam değişkeninize ekleyin: 
    go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
  3. Uygun OAuth kapsamlarını kullanarak API için erişim jetonu almak üzere oauth2l komutunu kullanın: 
    oauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform
     Örneğin, hizmet anahtarınız ~/myServiceKey-eb0a5f900ee3.json konumundaysa: 
    oauth2l fetch --credentials ~/myServiceKey-eb0a5f900ee3.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform
ya29.c.Elo4BmHXK5...

Kullanımla ilgili daha fazla bilgi için oauth2l README dosyasına bakın.

Google API İstemci Kitaplıkları

OAuth 2.0'ı kullanan Google API'leri için çeşitli istemci kitaplıkları mevcuttur. Seçtiğiniz dil hakkında daha fazla bilgi için Google API İstemci Kitaplıkları'na bakın.

Bu kitaplıkları Pub/Sub APIile kullanırken aşağıdaki kapsam dizelerini kullanın:

https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

Hatalar

Bu kılavuzla ilgili olarak aşağıdaki hata kodları döndürülebilir:

Hata Mesajı TBG Sorun giderme
Kamera görüntüsü artık indirilemiyor. DEADLINE_EXCEEDED Etkinlik resimlerinin süresi, etkinlik yayınlandıktan 30 saniye sonra dolar. Resmi süresi dolmadan önce indirdiğinizden emin olun.
Etkinlik kimliği kameraya ait değil. FAILED_PRECONDITION Kamera etkinliği tarafından döndürülen doğru eventID değerini kullanın.

API hata kodlarının tam listesi için API Hata Kodu Referansı'na bakın.