Etkinlikler

Etkinlikler eşzamansız olup Google Cloud Pub/Sub tarafından her Projectiçin tek bir konuda 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ı sağlanır.

Etkinlikleri etkinleştir

Etkinlikler, SDM API'nin isteğe bağlı bir özelliğidir. İlgili etkinlikleri Etkinlikleri etkinleştirme hakkında bilgi edinmek için Projectinceleyin.

Google Cloud Pub/Sub

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

Etkinlik aboneliği

Projectiçin etkinlikler etkinleştirildiğinde, söz konusu Project kimliğine özel olarak şu şekilde bir konu sağlanır:

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

Etkinlik almak için kullanım alanınıza bağlı olarak bu konuya pull veya push aboneliği oluşturun. SDM konusu için birden fazla abonelik desteklenir. Daha fazla bilgi için Abonelikleri yönetme bölümüne bakın.

Etkinlik başlatma

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. Tüm yapı ve cihazlarla ilgili etkinlikler bu çağrıdan 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 yayınlanacağını garanti etmez ve etkinliklerin makbuz sırası, etkinliklerin gerçekleştiği sıraya karşılık gelmeyebilir. Etkinlik sırasının mutabakatına yardımcı olması için timestamp alanını kullanın. Etkinlikler ayrıca tek bir etkinlik mesajında ayrı ayrı veya birleştirilmiş olarak da gelebilir.

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

User ID'ler

Uygulamanız yapı veya cihaz yerine kullanıcılara dayalıysa 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 kod 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 kaynak için yapılan ilişkisel güncellemeyi temsil eder. Örneğin, bir cihaz bir yapıya eklendiğinde veya cihaz bir yapıdan silindiğinde.

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

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

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

Yük

{
  "eventId" : "0be5c08d-0b45-4632-9d0f-f0830b2e426a",
  "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"
}

Bir ilişki etkinliğinde object, etkinliği tetikleyen kaynak, subject ise object öğesinin ilişkisinin olduğu kaynaktır. Yukarıdaki örnekte, user bir developeradlı kullanıcıya bu cihaza erişim izni vermiştir ve useradlı kullanıcının yetkili cihazı artık kendi yetkili yapısıyla ilişkilidir. Bu da etkinliği tetikler.

subject yalnızca bir oda veya yapı olabilir. a developer 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: "b1fedeb1-0cbd-4039-841f-694e15e39818"
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 bunların işleyiş şekli hakkında daha fazla bilgi için Etkinlikler bölümüne bakın.

Örnekler

Etkinlik yükleri her ilişki etkinliği türü için farklılık gösterir:

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"
}

Şu durumlarda ilişki etkinlikleri gönderilmez:

  • Bir oda silindi

Kaynak etkinlikleri

Kaynak etkinliği, bir kaynağa özel güncellemeyi temsil eder. Termostatın modunu değiştirmek gibi özellik alanındaki değişikliğe bağlı olarak ortaya çıkabilir. Ayrıca cihaz düğmesine basma gibi özellik alanını değiştirmeyen bir cihaz işlemini de temsil edebilir.

Özellik alanının değerinde yapılan 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" : "8ba08cdd-50ac-4652-ba32-3245d3e454bc",
  "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şiklik kaynak etkinliğinin yük biçimini anlamak için bağımsız özellik dokümanlarını kullanın.

Özellik alanını değiştirmeyen bir cihaz işlemine yanıt olarak oluşturulan bir etkinlik de resourceUpdate nesnesiyle birlikte traits nesnesi yerine events nesnesiyle yük içeriyor:

Yük

{
  "eventId" : "c6ad927f-12d0-4fa2-bfd6-d8260e77e614",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "P_xZPLCtP4wAbargQffMebl7nq...",
      }
    }
  }
  "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
  "eventThreadState" : "STARTED",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Bu kaynak etkinliği türleri belirli özelliklerle tanımlanır. Örneğin, Hareket etkinliği KameraMotion özelliğinde tanımlanır. Bu tür kaynak etkinliği türlerinin yük biçimini anlamak için her özelliğin belgelerine bakın.

Alanlar

Alan Açıklama Veri Türü
eventId Etkinliğin benzersiz tanımlayıcısıdır. string
Örnek: "c6ad927f-12d0-4fa2-bfd6-d8260e77e614"
timestamp Etkinliğin gerçekleştiği zaman. string
Örnek: "2019-01-01T00:00:01Z"
resourceUpdate Kaynak 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"
eventThreadId Etkinlik ileti dizisinin benzersiz tanımlayıcısı. string
Örnek: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
eventThreadState Etkinlik ileti dizisinin durumu. string
Değerler: "STARTED", "UPDATED", "ENDED"
resourceGroup Bu etkinliğe benzer güncellemelere sahip olabilecek kaynakları gösteren nesne. Etkinliğin kaynağı (resourceUpdate nesnesinden) her zaman bu nesnede bulunur. object

Farklı etkinlik türleri ve bunların işleyiş şekli hakkında daha fazla bilgi için Etkinlikler bölümüne bakın.

Güncellenebilir bildirimler

Kaynak etkinliklerine dayalı bildirimler, Android veya iOS gibi bir uygulamaya uygulanabilir. Gönderilen bildirim sayısını azaltmak için güncellenebilir bildirimler adı verilen bir özellik uygulanabilir. Bu özellikte mevcut bildirimler, aynı etkinlik ileti dizisinde sonraki etkinliklere dayalı olarak yeni bilgilerle güncellenir.

Güncellenebilir bildirimler için belirli etkinlikler özelliği desteği mevcuttur ve dokümanlarda Güncellenebilir  olarak etiketlenir. Bu etkinliklerin yüklerinde eventThreadId adlı ek bir alan bulunur. Kullanıcıya gösterilen mevcut bir bildirimi güncellemek amacıyla tek tek etkinlikleri birbirine bağlamak için bu alanı kullanın.

Etkinlik ileti dizisi, etkinlik oturumundan farklıdır. Etkinlik ileti dizisi, aynı ileti dizisindeki önceki bir etkinliğin güncel durumunu tanımlar. Etkinlik oturumu, birbiriyle ilişkili ayrı etkinlikler tanımlar ve belirli bir etkinlik oturumu için birden fazla etkinlik ileti dizisi olabilir.

Bildirim amacıyla, farklı etkinlik türleri farklı ileti dizileri halinde gruplandırılır.

Bu ileti dizisi gruplaması ve zamanlama mantığı, Google tarafından yönetilir ve herhangi bir zamanda değiştirilebilir. developer , bildirimleri SDM API tarafından sağlanan etkinlik ileti dizilerine ve oturumlara göre 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: Bir etkinlik ileti dizisindeki ilk etkinlik.
  • GÜNCELLENDİ: Devam eden bir ileti dizisindeki etkinlik. Tek bir ileti dizisinde bu duruma sahip sıfır veya daha fazla etkinlik olabilir.
  • SONA ERDİ: Bir etkinlik ileti dizisindeki son etkinlik. İleti dizisi türüne bağlı olarak, son GÜNCELLENEN etkinliğin kopyası olabilir.

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

Etkinlik filtreleme

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

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

Filtrelenen etkinlikler Google Home uygulamasında (GHA) useradlı cihazın etkinlik geçmişinde gösterilmeye devam eder. Ancak bu tür etkinlikler uygulama bildirimi oluşturmaz (söz konusu bildirim türü etkinleştirilmiş 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 ileti dizisinden 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 yerine bir uygulama veya sanal makine tarafından kullanılır ve kendi benzersiz hesap anahtarına sahiptir.

Pub/Sub API için hizmet hesabı yetkilendirmesi İki aşamalı OAuth (2LO) yöntemini kullanır.

2LO yetkilendirme akışında:

  • developer , hizmet anahtarı kullanarak erişim jetonu ister.
  • developer , erişim jetonunu API'ye yapılan çağrılarda 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 bölümüne bakın.

Yetkilendirme

Hizmet hesabı, Pub/Sub API ile kullanım için 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. Sadece Pub/Sub Abonesi rolü vermenizi öneririz. Hizmet hesabı anahtarını Pub/Sub API'yi kullanacak makineye indirdiğinizden emin olun.
  3. Bir önceki adımda sayfada bulunan talimatları uygulayarak kimlik doğrulama kimlik bilgilerinizi (hizmet hesabı anahtarı) uygulama kodunuza sağlayın. API erişimini hızlı bir şekilde test etmek istiyorsanız oauth2l kullanarak 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, OAuth için Go'da yazılmış bir komut satırı aracıdır. Bu aracı Mac veya Linux için Go kullanarak yükleyin.

  1. Sisteminizde Go uygulaması 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 amacıyla 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 şu konumdaysa: ~/myServiceKey-eb0a5f900ee3.json: 
    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 oauth2l BENİOKU bölümüne bakın.

Google API İstemci Kitaplıkları

Google API'leri için OAuth 2.0'ı kullanan ç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ı RPC Sorun giderme
Kamera görseli artık indirilemiyor. DEADLINE_EXCEEDED Etkinlik resimlerinin 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 etkinliğinin 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.