Etkinlikler

Etkinlikler eşzamansız olup Google Cloud Pub/Sub tarafından yönetilir. 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ı sağlanır.

Etkinlikleri etkinleştir

Etkinlikler, SDM API'sinin isteğe bağlı bir özelliğidir. Bu etkinlikleri Etkinlikleri etkinleştirme bölümünden için nasıl etkinleştireceğinizi öğrenebilirsiniz 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

Projectiçin etkinlikler etkinleştirildiğinde, Project kimliğine özel bir konu sağlanır. Bu konu şu şekilde görünür:

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

Etkinlik almak için kullanım alanınıza bağlı olarak söz konusu konuyla ilgili bir pull 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.

Etkinlikleri başlatma

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

Örnek olarak, 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ınması sırası, etkinliklerin gerçekte gerçekleştiği sıraya karşılık gelmeyebilir. Etkinlik sırasının uyumlaştırılmasına yardımcı olmak için timestamp alanını kullanın. Etkinlikler tek tek veya tek bir etkinlik mesajında birleştirilerek de gönderilebilir.

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 karartılmış bir kimliktir.

userID, her API çağrısının HTTP yanıt üst bilgisinde de kullanılabilir.

İlişki etkinlikleri

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

  • CREATED
  • SİLİNDİ
  • GÜNCELLENDİ

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

Yük

{
  "eventId" : "049ce833-c330-476f-952f-b3dda83ae0f6",
  "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 kaynaktır ve subject, object'ün artık ilişkili olduğu kaynaktır. Yukarıdaki örnekte, user bir developer'ye bu cihaza erişim izni vermiştir ve user'nin yetkili cihazı artık 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 izniniz 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: "665fa8b2-ba4a-401f-aad7-bd2740f7ec41"
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, 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 başlıklı makaleyi inceleyin.

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

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

  • Bir oda silindiğinde

Kaynak etkinlikleri

Kaynak etkinliği, bir kaynağa özgü güncellemeyi temsil eder. Bu durum, bir özellik alanının değerinde yapılan bir değişikliğe (ör. termostatın modunun değiştirilmesi) yanıt olarak gerçekleşebilir. 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 bir değişikliğe yanıt olarak oluşturulan bir etkinlik, cihaz GET çağrısına benzer şekilde bir traits nesnesi içerir:

Yük

{
  "eventId" : "d89bda44-0d9d-42aa-9ab2-a685a0f1ca0d",
  "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.

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

Yük

{
  "eventId" : "d7b54476-0d5d-4d37-8d80-14261981144b",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "E5kcTftnwgacvbdKS69vufvvP0...",
      }
    }
  }
  "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 CameraMotion ö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ı. string
Örnek: "d7b54476-0d5d-4d37-8d80-14261981144b"
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 içeren bir nesne. object
userId Kullanıcıyı temsil eden benzersiz, karartılmış bir tanımlayıcı. string
Örnek: "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi"
eventThreadId Etkinlik mesaj dizisinin benzersiz tanımlayıcısı. string
Örnek: "d67cd3f7-86a7-425e-8bb3-462f92ec9f59"
eventThreadState Etkinlik mesaj dizisinin durumu. string
Değerler: "STARTED", "UPDATED", "ENDED"
resourceGroup Bu etkinlikle benzer güncellemelere sahip olabilecek kaynakları belirten bir 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 başlıklı makaleyi inceleyin.

Güncellenebilecek 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 özellikte, mevcut bildirimler aynı etkinlik mesaj dizisindeki sonraki etkinliklere göre yeni bilgilerle güncellenir.

Belirli etkinlikler, güncellenebilir bildirimler için destek sunar ve belgelerde Güncellenebilir  olarak etiketlenir. Bu etkinliklerin yüklerinde eventThreadId adlı ek bir alan bulunur. Bir kullanıcıya gösterilen mevcut bir bildirimi güncellemek amacıyla ayrı etkinlikleri birbirine bağlamak için bu alanı kullanın.

Etkinlik mesaj dizisi, etkinlik oturumuyla aynı değildir. Etkinlik mesaj dizisi, aynı mesaj 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 mesaj dizisi olabilir.

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

Bu mesaj dizisi gruplandırma 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.

Mesaj dizisi durumu

Güncellenebilir bildirimleri destekleyen etkinliklerde, etkinlik ileti dizisinin o andaki durumunu belirten bir eventThreadState alanı da bulunur. Bu alanın değerleri şunlardır:

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

Bu alan, bir etkinlik ileti dizisinin 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ınlanmadan filtrelenebilir. Bu davranışa etkinlik filtreleme denir. Etkinlik filtrelemenin amacı, kısa süre içinde çok fazla benzer etkinlik mesajı yayınlanmasını önlemektir.

Örneğin, ilk bir hareket etkinliği için bir SDM konusuna mesaj yayınlanabilir. Sonrasında Motion için diğer mesajlar, belirli bir süre geçene kadar filtrelenerek yayınlanmadan çıkarılır. 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), filtrelenen etkinlikler user'ın etkinlik geçmişinde gösterilmeye devam eder. Ancak bu tür etkinlikler, bildirim türü etkin 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 mesaj dizisi 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 özgü bir hesap anahtarına sahiptir.

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 , erişim jetonunu API çağrılarında 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ılmak üzere yetkilendirilmiş olmalıdır:

  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. Kanala 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 yer alan talimatları uygulayarak kimlik doğrulama kimlik bilgilerinizi (hizmet hesabı anahtarı) uygulama kodunuza ekleyin veya API erişimini hızlıca test etmek istiyorsanız oauth2l kullanarak manuel olarak erişim jetonu alın.
  4. Mesajları almak ve onaylamak için hizmet hesabı kimlik bilgilerini veya erişim jetonunu Pub/Sub project.subscriptions API ile kullanın.

oauth2l

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

  1. Sisteminizde Go yoksa önce Go'yu 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 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 oauth2l README dosyasını inceleyin.

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 indirilemez. DEADLINE_EXCEEDED Etkinlik resimlerinin süresi, etkinlik yayınlandıktan 30 saniye sonra dolar. Süre dolmadan önce resmi indirin.
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.