Etkinlikler eşzamansız olup Google Cloud Pub/Sub tarafından yönetilir. Her Projectiçin tek bir konuda yönetilir. 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:
- Nasıl yapılır? kılavuzlarını inceleyerek Pub/Sub hakkındaki temel bilgileri edinin.
- Kimlik doğrulamanın işleyiş şeklini anlayın.
- Sağlanan bir istemci kitaplığını seçin veya kendi kitaplığınızı yazıp REST/HTTP veya gRPC API yüzeylerini kullanın.
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.
Etkinlik 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.
Örneğ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ı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 dayanıyorsa 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" : "d5c0f0bd-de65-44fd-ac60-686c302e56eb", "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
'nin artık ilişkili olduğu kaynaktır. Yukarıdaki örnekte, bir user , belirli bir cihaza erişim izni vermiş bir developer'e 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 , user'un yapı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: "64b87b46-1aec-42a4-8c01-997a407814df" |
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 içeren 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ükü, 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, 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 bir ö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" : "a88bc884-d2b8-42d6-adba-b7be92c232a3",
"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ğinin yükü biçimini anlamak için özellikle ilgili dokümanları 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" : "4f80de08-1b77-42a4-b33e-40876a2a1865",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion
" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "MWJ253hZMPAsJZJWbrGM4ThsKM...", } } } "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 belgelerine bakın.
Alanlar
Alan | Açıklama | Veri Türü |
---|---|---|
eventId |
Etkinliğin benzersiz tanımlayıcısı. | string Örnek: "4f80de08-1b77-42a4-b33e-40876a2a1865" |
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 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 dizilerinde gruplandırılır.
Bu mesaj dizisi gruplandırma ve zamanlama mantığı Google tarafından yönetilir ve herhangi bir zamanda değiştirilebilir. A developer , bildirimleri SDM API tarafından sağlanan etkinlik mesaj 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 iş akışında 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. Bu tarihten sonra Motion için gönderilen diğer mesajlar, belirli bir süre geçene kadar yayınlanmaz. 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 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 yetkilendirilmiş olmalıdır:
- Google Cloud'da Cloud Pub/Sub API'yi etkinleştirin.
- Hizmet hesabı oluşturma bölümünde açıklandığı gibi bir hizmet hesabı ve hizmet hesabı anahtarı oluşturun. Bu kullanıcıya yalnızca Pub/Sub Abonesi rolünü atamanız önerilir. Hizmet hesabı anahtarını, Pub/Sub API'yi kullanacak makineye indirdiğinizden emin olun.
- Ö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. - 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.
- Sisteminizde Go yoksa önce Go'yu indirip yükleyin.
- Go yüklendikten sonra
oauth2l
'ü yükleyin ve konumunuPATH
ortam değişkeninize ekleyin:go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
- Uygun OAuth kapsamlarını kullanarak API için erişim jetonu almak üzere
oauth2l
kullanın:
Örneğin, hizmet anahtarınızoauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
~/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. Tercih ettiğ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 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.