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:
- "Nasıl Yapılır?" kılavuzlarıyla Pub/Sub hakkındaki temel bilgileri öğrenin.
- Kimlik doğrulamanın işleyiş şekli hakkında bilgi sahibi olun.
- Sağlanan bir İstemci Kitaplığı'nı seçin ya da kendinizinkini yazın ve REST/HTTP veya gRPC API yüzeylerini kullanın.
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 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:
- Google Cloud'da Cloud Pub/Sub API'yi etkinleştirin.
- 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.
- Ö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. - 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.
- Sisteminizde Go yoksa önce uygulamayı indirip yükleyin.
- Go yüklendikten sonra
oauth2l
uygulamasını 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 bir 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
BENİ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.