Etkinlikler

Etkinlikler eşzamansız olup Google Cloud Pub/Sub tarafından her Projectiçin tek bir konu olacak şekilde yönetilir. Etkinlikler, tüm cihazlar ve yapılar için güncelleme 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'sinin isteğe bağlı bir özelliğidir. Etkinlikleri etkinleştirme etkinliğinizi Projecthesabınızda nasıl etkinleştireceğinizi öğrenin.

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

Projectiçin etkinlikler etkinleştirildiğinde, bu Project kimliğine özel şu biçimde bir konu sağlanır:

projects/sdm-prod/topics/enterprise-project-id

Etkinlikleri almak için kullanım alanınıza bağlı olarak ilgili konuya pull veya push aboneliği oluşturun. Birden fazla SDM konusuna abonelik desteklenir. Daha fazla bilgi için bkz. Abonelikleri yönetme.

Etkinlik başlatma

Pub/Sub aboneliği oluşturulduktan sonra ilk kez etkinlik başlatmak için tek seferlik tetikleyici olarak bir devices.list API çağrısı yapın. Tüm yapı ve cihazlar için etkinlikler bu görüşmeden sonra yayınlanacak.

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

Etkinlik sırası

Pub/Sub, etkinliklerin sıralı olarak iletileceğini garanti etmez ve etkinliklerin makbuz sırası, etkinliklerin gerçekleştiği sıraya karşılık gelmeyebilir. Etkinlik sırası mutabakatına yardımcı olması için timestamp alanını kullanın. Etkinlikler de ayrı ayrı veya tek bir etkinlik mesajı halinde gelebilir.

Daha fazla bilgi için Mesaj sıralama bölümüne bakın.

User ID'ler

Uygulamanız kullanıcılara dayalıysa (yapı veya cihaz yerine) 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 ve kod karartılmış bir kimliktir.

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

İlişki etkinlikleri

İlişki etkinlikleri, bir kaynak için ilişkisel güncellemeyi 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İ

Bir ilişki etkinliğinin yükü aşağıdaki gibidir:

Yük

{
  "eventId" : "eed9763a-8735-45d9-81d9-e0621c130eb1",
  "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 öğesinin artık ilişki kurduğu kaynaktır. Yukarıdaki örnekte, user bu spesifik cihaza bir developeriçin erişim izni vermiştir ve useradlı kullanıcının yetkilendirildiği cihaz artık etkinliği tetikleyen yetkili yapısıyla ilgilidir.

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

Alanlar

Alan Açıklama Veri Türü
eventId Etkinliğin benzersiz tanımlayıcısıdır. string
Örnek: "1362476b-4ac4-4608-a8be-4c8cf4101426"
timestamp Etkinliğin gerçekleştiği zaman. string
Örnek: "2019-01-01T00:00:01Z"
relationUpdate İlişki güncellemesiyle ilgili bilgileri ayrıntılandıran bir nesne. object
userId Kullanıcıyı temsil eden benzersiz ve kodu karartılmış bir tanımlayıcı. string
Örnek: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"

Farklı etkinlik türleri ve bu etkinliklerin işleyiş şekli hakkında daha fazla bilgi edinmek için Etkinlikler bölümünü 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

Kaynak etkinlikleri

Kaynak etkinlikleri, bir kaynağa özgü güncellemeyi temsil eder. Termostat modunun değiştirilmesi gibi, özellik alanındaki bir değişikliğe tepki olarak olabilir. Ayrıca, cihaz düğmesine basma gibi bir özellik alanını değiştirmeyen cihaz işlemlerini de temsil edebilir.

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

Yük

{
  "eventId" : "5b98a768-6771-4d4d-836d-58cce3a62cca",
  "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 kaynak etkinliğinde yük biçimini anlamak için bireysel özellik belgelerini kullanın.

Bir özellik alanını değiştirmeyen bir cihaz işlemine yanıt olarak oluşturulan etkinlik aynı zamanda resourceUpdate nesnesine sahip ancak traits nesnesi yerine events nesnesi içeren bir yük içerir:

Yük

{
  "eventId" : "3426d266-406b-48f3-9595-5192229a39a0",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "8XZ1cQ76Becovj551YfM9ZnuwB...",
      }
    }
  }
  "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 özelliklerle tanımlanır. Örneğin, Motion etkinliği KameraMotion özelliğinde tanımlanır. Bu tür kaynak etkinliklerinin yük biçimini anlamak için özellik belgelerine bakın.

Alanlar

Alan Açıklama Veri Türü
eventId Etkinliğin benzersiz tanımlayıcısıdır. string
Örnek: "3426d266-406b-48f3-9595-5192229a39a0"
timestamp Etkinliğin gerçekleştiği zaman. string
Örnek: "2019-01-01T00:00:01Z"
resourceUpdate Kaynak güncellemesiyle ilgili bilgileri ayrıntılı şekilde gösteren bir nesne. object
userId Kullanıcıyı temsil eden benzersiz ve kodu karartılmış bir tanımlayıcı. string
Örnek: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
eventThreadId Etkinlik ileti dizisinin benzersiz tanımlayıcısıdır. string
Örnek: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
eventThreadState Etkinlik ileti dizisinin durumu. string
Değerler: "STARTED", "UPDATED", "ENDED"
resourceGroup Bu etkinlikle benzer güncellemelere sahip olabilecek kaynakları gösteren bir nesne. Etkinliğin kaynağı (resourceUpdate nesnesinden) bu nesnede her zaman bulunur. object

Farklı etkinlik türleri ve bu etkinliklerin işleyiş şekli hakkında daha fazla bilgi edinmek için Etkinlikler bölümünü inceleyin.

Güncellenebilir bildirimler

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

Güncellenebilir bildirimler için belirli etkinlikler özelliği desteği sunulur ve belgelerde Güncellenebilir  olarak etiketlenir. Bu etkinliklerin yükünde eventThreadId adlı ek bir alan vardır. Bir kullanıcıya sunulan mevcut bir bildirimi güncellemek amacıyla etkinlikleri tek tek birbirine bağlamak için bu alanı kullanın.

Etkinlik ileti dizisi, etkinlik oturumuyla aynı değildir. Etkinlik ileti dizisi, aynı ileti dizisindeki önceki bir etkinliğin güncellenmiş 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.

Bildirim amacıyla farklı etkinlik türleri, farklı iş parçacıklarında gruplandırılır.

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

İleti dizisi durumu

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

  • BAŞLADI: Etkinlik ileti dizisindeki ilk etkinlik.
  • GÜNCELLENDİ: Devam eden bir etkinlik ileti dizisindeki bir etkinlik. Tek bir ileti dizisinde bu duruma sahip sıfır veya daha fazla etkinlik olabilir.
  • BİTTİ: Bir etkinlik ileti dizisindeki son etkinliktir. İleti dizisi türüne bağlı olarak, son UPDATED etkinliğinin kopyası olabilir.

Bu alan, bir etkinlik ileti dizisinin ilerlemesini ve ne zaman sona erdiğini izlemek için kullanılabilir.

Etkinlik filtreleme

Bazı durumlarda, bir cihaz tarafından algılanan etkinlikler filtrelenerek SDM Pub/Sub konusuna yayınlanmayabilir. Bu davranışa etkinlik filtreleme denir. Etkinlik filtrelemenin amacı, kısa bir süre içinde çok fazla sayıda benzer etkinlik mesajı yayınlamaktan kaçınmaktır.

Örneğin, bir mesaj ilk Hareket etkinliği için bir SDM konusunda yayınlanabilir. Bundan sonra Hareket için olan diğer mesajlar, belirli bir süre geçene kadar yayınlama için filtrelenir. Bu süre geçtikten sonra, söz konusu etkinlik türü için bir etkinlik mesajı tekrar yayınlanabilir.

Google Home uygulamasında (GHA), filtrelenmiş etkinlikler useradlı kişinin etkinlik geçmişinde görünmeye devam eder. Ancak bu tür etkinlikler uygulama bildirimi oluşturmaz (söz konusu bildirim türü etkin olsa bile).

Her etkinlik türünün, Google tarafından tanımlanan ve herhangi bir zamanda değişebilen kendi etkinlik filtreleme mantığı vardır. Bu etkinlik filtreleme mantığı, etkinlik iş parçacığından 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 kendi benzersiz hesap anahtarı vardır.

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

2LO yetkilendirme akışında:

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

Google 2LO ve kurulumun nasıl yapılacağı hakkında daha fazla bilgi edinmek için Sunucudan Sunucuya Uygulamalar için OAuth 2.0'ı Kullanma sayfasına göz atın.

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ığı şekilde bir hizmet hesabı ve hizmet hesabı anahtarı oluşturun. Bu kullanıcıya yalnızca Pub/Sub Abonesi rolü vermenizi öneririz. Hizmet hesabı anahtarını, Pub/Sub API'yi kullanacak makineye indirdiğinizden emin olun.
  3. Önceki adımdaki sayfada bulunan 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 ile manuel olarak bir erişim jetonu alın.
  4. Mesajları almak ve onaylamak için hizmet hesabı kimlik bilgilerini veya Pub/Sub project.subscriptions API ile erişim jetonunu kullanın.

oauth2l

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

  1. Sisteminizde Go yoksa önce uygulamayı indirip yükleyin.
  2. Go yüklendikten sonra oauth2l uygulamasını 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 bir erişim jetonu almak üzere oauth2l 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 adresindeyse: 
    oauth2l fetch --credentials ~/myServiceKey-eb0a5f900ee3.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform
ya29.c.Elo4BmHXK5...

Daha fazla kullanım bilgisi için oauth2lBENİOKU sayfasına göz atın.

Google API İstemci Kitaplıkları

OAuth 2.0'ı kullanan Google API'leri için çeşitli istemci kitaplıkları vardır. 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ı RPC Sorun giderme
Kamera resmi artık indirilemiyor. DEADLINE_EXCEEDED Etkinlik görüntülerinin süresi, etkinlik yayınlandıktan 30 saniye sonra dolar. Resmi, süresi dolmadan önce indirmeyi unutmayın.
Etkinlik kimliği kameraya ait değil. FAILED_PRECONDITION Kamera olayının döndürdüğü doğru eventID değerini kullanın.

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