Etkinlikler

Etkinlikler eşzamansızdır ve Google Cloud Pub/Sub tarafından Projectbaşına 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ı garanti edilir.

Etkinlikleri etkinleştir

Etkinlikler, SDM API'nin isteğe bağlı bir özelliğidir. Etkinlikleri etkinleştirme bölümüne bakarak bunları nasıl etkinleştireceğinizi öğrenin Project.

Google Cloud Pub/Sub

Pub/Sub'ın nasıl çalıştığı 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 öğrenin.
• Kimlik doğrulamanın işleyiş şeklini öğrenin.
• Sağlanan istemci kitaplıklarından birini seçin veya kendi istemci kitaplığınızı yazıp REST/HTTP ya da gRPC API yüzeylerini kullanın.

Etkinlik aboneliği

Ocak 2025'ten önce, Projectiçin etkinlikler etkinleştirilmişse size Project kimliğine özel, Google tarafından barındırılan bir konu sağlanmış olurdu. Bu konu şu biçimlerde olurdu:

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

Tüm projelerin artık Pub/Sub konularını kendi Google Cloud projelerinde kendi bünyesinde barındırması gerekiyor (Ocak 2025'ten itibaren yeni projeler için zorunlu, 30 Kasım 2026'ya kadar tüm mevcut projeler için gerekli). Bu işlem şu şekilde yapılabilir:

projects/gcp-project-name/subscriptions/topic-id

project , kendi Google Cloud projenizde barındırılan bir konu kullanıyorsa herhangi bir işlem yapmanız gerekmez. Pub/Sub konu yapılandırmanızı taşıdığınızda mevcut kullanıcı erişim jetonları veya OAuth izinleri geçersiz kılınmaz. Kendi kendine barındırılan konular ve abonelikler standart Google Cloud Pub/Sub fiyatlandırmasına (ayda 10 GB'lık ücretsiz katman dahil) tabidir. Daha fazla bilgi için Konu oluşturma başlıklı makaleyi inceleyin.

Etkinlikleri almak için kullanım alanınıza bağlı olarak ilgili konuda 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 tetikleyici olarak devices.list API çağrısı yapın. Bu çağrıdan sonra tüm yapı ve cihazlara ait etkinlikler yayınlanır.

Örnek iç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ınma sırası, etkinliklerin gerçekte gerçekleştiği sırayla eşleşmeyebilir. Etkinlik sırasının mutabakatına yardımcı olması için timestamp alanını kullanın. Etkinlikler tek tek veya tek bir etkinlik mesajında birleştirilmiş olarak da gelebilir.

Daha fazla bilgi için Mesajları sıralama başlıklı makaleyi inceleyin.

User ID'ler

Uygulamanız yapı veya cihaz yerine kullanıcıları temel alı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 başlığında da bulunur.

İlişki etkinlikleri

İlişki etkinlikleri, bir kaynak için ilişkisel güncellemeyi temsil eder. Örneğin, bir yapıya cihaz eklendiğinde veya bir yapıdan cihaz silindiğinde.

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

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

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

{
  "eventId" : "7c786f36-8068-4b86-ba67-d6e0d28ebb11",
  "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, user bu cihaza erişim iznini bir developerkullanıcısına vermiştir ve userkullanıcısının yetkili cihazı artık yetkili yapısıyla ilişkilidir. Bu durum, etkinliği tetikler.

subject yalnızca bir oda veya yapı olabilir. a developer , user'nın yapısını görüntüleme iznine sahip değilse subject her zaman boş olur.

Alanlar

Farklı etkinlik türleri ve işleyiş şekilleri 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ıdır:

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

"relationUpdate" : {
  "type" : "CREATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

"relationUpdate" : {
  "type" : "UPDATED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "",
  "object" : "enterprises/project-id/structures/structure-id"
}

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id",
  "object" : "enterprises/project-id/devices/device-id"
}

"relationUpdate" : {
  "type" : "DELETED",
  "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id",
  "object" : "enterprises/project-id/devices/device-id"
}

İlişki etkinlikleri aşağıdaki durumlarda gönderilmez:

• Bir oda silindiğinde

Kaynak etkinlikleri

Kaynak etkinliği, kaynağa özgü bir güncellemeyi temsil eder. Bu, bir özellik alanının değerindeki değişikliğe (ör. termostatın modunu değiştirme) yanıt olarak gerçekleşebilir. 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ğerindeki 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:

{
  "eventId" : "59381967-62e1-427b-98b8-67d5dbbd590c",
  "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 kaynağı etkinliğinin yük biçimini anlamak için bireysel özellik dokümanlarını kullanın.

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

{
  "eventId" : "1608503f-fedf-43cc-b29c-aa4e3b685a60",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "Ki0F7T-Joca_uRg42loDugGevl...",
      }
    }
  }
  "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 dokümanlarını inceleyin.

Alanlar

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

Güncellenebilir bildirimler

Belirli etkinlikler, güncellenebilir bildirimler için özellik desteği 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 iş parçacığı, aynı iş parçacığındaki ö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ı ileti dizilerinde gruplandırılır.

Bu ileti grubu ve zamanlama mantığı Google tarafından yönetilir ve herhangi bir zamanda değişebilir. A developer , bildirimleri SDM API tarafından sağlanan etkinlik mesaj dizilerine ve oturumlara göre güncellemelidir.

İleti dizisi durumu

Güncellenebilir bildirimleri destekleyen etkinliklerde, etkinlik dizisinin o anki durumunu gösteren bir eventThreadState alanı da bulunur. Bu alan aşağıdaki değerlere sahiptir:

• STARTED: Bir etkinlik ileti dizisindeki ilk etkinlik.
• UPDATED: Devam eden bir etkinlik iş parçacığındaki etkinlik. Tek bir ileti dizisinde bu duruma sahip sıfır veya daha fazla etkinlik olabilir.
• ENDED: Bir etkinlik dizisindeki son etkinliktir. Dizinin türüne bağlı olarak, son UPDATED etkinliğinin kopyası olabilir.

Bu alan, bir etkinlik mesaj 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 konusunda yayınlanmayacak şekilde filtrelenebilir. Bu davranışa etkinlik filtreleme adı verilir. Etkinlik filtrelemenin amacı, kısa süre içinde çok fazla benzer etkinlik mesajı yayınlamayı önlemektir.

Örneğin, ilk hareket etkinliği için bir SDM konusuna mesaj yayınlanabilir. Bundan sonra Motion ile ilgili diğer mesajlar, belirli bir süre geçene kadar yayınlanmadan 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), filtrelenen etkinlikler usercihazının olay geçmişinde gösterilmeye devam eder. Ancak bu tür etkinlikler, uygulama bildirimi oluşturmaz (bu bildirim türü etkinleştirilmiş olsa bile).

Her etkinlik türünün, Google tarafından tanımlanan ve her an değiştirilebilecek kendi etkinlik filtreleme mantığı vardır. Bu etkinlik filtreleme mantığı, etkinlik iş parçacığı 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ına sahiptir.

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

2LO yetkilendirme akışında:

• developer , hizmet anahtarı kullanarak erişim jetonu ister.
• developer , API çağrılarıyla erişim jetonunu kullanır.

Google 2LO ve nasıl ayarlanacağı 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 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 hizmet hesabına yalnızca Pub/Sub Abonesi rolünü vermenizi öneririz. Hizmet hesabı anahtarını, Pub/Sub API'nin kullanılacağı makineye indirdiğinizden emin olun.
3. Önceki adımda belirtilen sayfadaki talimatları uygulayarak kimlik doğrulama bilgilerinizi (hizmet hesabı anahtarı) uygulama kodunuza sağlayın veya API erişimini hızlıca test etmek istiyorsanız oauth2l aracını kullanarak manuel olarak erişim jetonu alın.
4. İletileri çekmek ve onaylamak için hizmet hesabı kimlik bilgilerini veya Pub/Sub project.subscriptions API ile erişim jetonunu kullanın.

oauth2l

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

1. Sisteminizde Go yoksa önce indirip yükleyin.
2. Go yüklendikten sonra oauth2l aracı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 öğesini 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 konumundaysa:

   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 dosyasına bakın.

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 istemci kitaplıkları sayfasını inceleyin.

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:

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