Etkinlikler

Etkinlikler eşzamansızdır ve 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ı garanti edilir.

Etkinlikleri etkinleştir

Etkinlikler, SDM API'nin isteğe bağlı bir özelliğidir. Etkinlikleri nasıl etkinleştireceğinizi öğrenmek için Etkinlikleri etkinleştirme başlıklı makaleyi inceleyin. 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ı ile 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, etkinlikler Projectiçin etkinleştirilmişse size bu kimliğe özel, Google tarafından barındırılan bir konu Project şu biçimde sağlanırdı:

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

Artık tüm projelerin Pub/Sub konularını kendi Google Cloud projelerinde barındırması gerekiyor (Ocak 2025'ten itibaren yeni projeler için zorunlu, mevcut tüm projeler için ise 30 Kasım 2026'ya kadar zorunlu). Bu konular şu biçimde olmalıdır:

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

project Google Cloud projenizde zaten kendi kendine barındırılan bir konu kullanıyorsanız 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 bir 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 kaynağın ilişkisel güncellemesini 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" : "768e4eea-b61d-428b-8926-c67e2abaddf9",
  "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 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ı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, bir kaynağa özgü güncellemeyi temsil eder. Özellik alanının değerindeki bir değişikliğe (ör. termostatın modunu değiştirme) yanıt olarak gönderilebilir. 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" : "ae3f760e-9e1f-4c14-b911-28482e86e56d",
  "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 bireysel özellik belgelerini 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" : "aecdfca3-25ec-4738-bdbf-d24c4a209d93",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "jE1ZfUIAp6z2anjwTJp5E8QxvC...",
      }
    }
  }
  "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ına bakın.

Alanlar

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

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üncellenen 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ı mesaj dizilerinde gruplandırılır.

Bu ileti dizisi gruplandırma ve zamanlama mantığı Google tarafından yönetilir ve herhangi bir zamanda değiştirilebilir. A developer , SDM API tarafından sağlanan etkinlik iş parçacıklarına ve oturumlara göre bildirimleri güncellemelidir.

İleti dizisi durumu

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

• BAŞLATILDI (STARTED): Bir etkinlik dizisindeki ilk etkinlik.
• UPDATED: Devam eden bir etkinlik iş parçacığındaki etkinlik. Tek bir iş parçacığında bu durumda sıfır veya daha fazla etkinlik olabilir.
• SONLANDIRILDI (ENDED): Etkinlik dizisindeki son etkinliktir. Dizi türüne bağlı olarak, son GÜNCELLENDİ (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 konusuna yayınlanmaktan filtrelenebilir. Bu davranışa etkinlik filtreleme denir. Etkinlik filtrelemenin amacı, kısa bir süre içinde çok fazla benzer etkinlik mesajı yayınlanmasını önlemektir.

Örneğin, ilk hareket etkinliği için bir SDM konusuna mesaj yayınlanabilir. Bu sürenin ardından, Hareket 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 usercihazının olay geçmişinde gösterilmeye devam eder. Ancak bu tür etkinlikler, bildirim türü etkinleştirilmiş olsa bile uygulama bildirimi oluşturmaz.

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 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 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. Yalnızca Pub/Sub Abonesi rolünü vermenizi öneririz. Hizmet hesabı anahtarını Pub/Sub API'yi kullanacak makineye indirdiğinizden emin olun.
3. Önceki adımda yer alan 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 kullanarak erişim jetonunu manuel olarak 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 dilinde 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 indirip yükleyin.
2. Go yüklendikten sonra oauth2l'yı 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 konumundaysa:

   oauth2l fetch --credentials ~/myServiceKey-eb0a5f900ee3.json --scope https://www.googleapis.com/auth/pubsub
   https://www.googleapis.com/auth/cloud-platform
   ya29.c.Elo4BmHXK5...

Kullanımla ilgili daha fazla bilgi 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 İ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:

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