Zdarzenia są asynchroniczne i zarządzane przez Google Cloud Pub/Sub w jednym temacie na ProjectZdarzenia zapewniają aktualizacje dotyczące wszystkich urządzeń i obiektów, a odbiór zdarzeń jest dopóki token dostępu nie zostanie unieważniony przez użytkownika, a komunikaty o zdarzeniu nie wygasła.
Włącz wydarzenia
Zdarzenia to opcjonalna funkcja interfejsu SDM API. Zobacz Włącz zdarzenia , by dowiedzieć się, jak włączyć je na koncie Project.
Google Cloud Pub/Sub
Więcej informacji znajdziesz w dokumentacji Google Cloud Pub/Sub. o sposobie działania Pub/Sub. W szczególności:
- Poznaj podstawy Pub/Sub Instrukcje.
- Dowiedz się, jak działa Uwierzytelnianie.
- Wybierz udostępnianą Bibliotekę klienta. lub utwórz własny i użyj Platformy interfejsu API REST/HTTP lub gRPC.
Subskrypcja zdarzenia
Gdy włączysz wydarzenia w przypadku tego wydarzenia ( Project), otrzymasz informację na ten temat Project Identyfikator w formie:
projects/sdm-prod/topics/enterprise-project-id
Aby odbierać zdarzenia, utwórz pobieranie lub push na dany temat, w zależności od dla każdego przypadku użycia. Obsługiwane jest wiele subskrypcji tematu SDM. Zobacz Zarządzanie subskrypcjami i informacjami o nich.
Inicjowanie zdarzeń
Aby zainicjować zdarzenia po raz pierwszy po utworzeniu subskrypcji Pub/Sub, utwórz
devices.list
Wywołanie interfejsu API jako jednorazowe wywołanie. Zdarzenia dotyczące wszystkich obiektów i urządzeń zostaną opublikowane po tym terminie
połączenie.
Na przykład zobacz Strona Autoryzuj w krótkim przewodniku Przewodnik.
Kolejność wydarzeń
Pub/Sub nie gwarantuje zamówionego dostarczania zdarzeń, a kolejność ich otrzymywania może nie być
zgodnie z kolejnością, w jakiej zdarzenia faktycznie wystąpiły. Użyj funkcji timestamp
ułatwiające uzgadnianie kolejności zdarzeń. Wydarzenia mogą też pojawiać się pojedynczo lub łącznie
w jedną wiadomość o zdarzeniu.
Więcej informacji: Porządkowanie wiadomości.
Identyfikatory użytkowników
Jeśli Twoja implementacja jest oparta na użytkownikach (a nie strukturze czy urządzeniu), zastosuj
userID
z ładunku zdarzenia, aby skorelować zasoby i zdarzenia. To pole jest
zaciemniony identyfikator reprezentujący konkretnego użytkownika.
Identyfikator userID
jest też dostępny w nagłówku odpowiedzi HTTP każdego wywołania interfejsu API.
Zdarzenia związane z relacją
Zdarzenia relacji reprezentują relacyjną aktualizację zasobu. Jeśli na przykład urządzenie jest po dodaniu do domu lub usunięciu urządzenia z domu.
Wyróżniamy 3 typy zdarzeń relacji:
- UTWORZONO
- USUNIĘTY
- ZAKTUALIZOWANO
Ładunek zdarzenia relacji wygląda tak:
Ładunek
{ "eventId" : "b2283cc4-26ab-404d-b5bf-7a29e7821f74", "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" }
W zdarzeniu relacji object
to zasób, który wywołał zdarzenie oraz
subject
to zasób, z którym zasób object
ma teraz powiązanie. W
powyżej: użytkownik user przyznał dostęp do tego konkretnego urządzenia
developer, a autoryzowane urządzenie użytkownika userjest teraz powiązane z
do wywołania zdarzenia.
subject
może być tylko pomieszczeniem lub domem. Jeśli a developer nie ma
uprawnienia do wyświetlania struktury user, subject
to zawsze
puste.
Pola
Pole | Opis | Typ danych |
---|---|---|
eventId |
Unikalny identyfikator zdarzenia. | string Przykład: „73a35b49-6be6-4ac3-9ec7-5adaaab33ea6” |
timestamp |
Czas wystąpienia zdarzenia. | string Przykład: „2019-01-01T00:00:01Z” |
relationUpdate |
Obiekt ze szczegółowymi informacjami o aktualizacji relacji. | object |
userId |
Unikalny, zaciemniony identyfikator reprezentujący użytkownika. | string Przykład: „AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi” |
Więcej informacji o różnych zdarzeniach znajdziesz w sekcji Zdarzenia. typów zdarzeń i sposobu ich działania.
Przykłady
Ładunki zdarzeń różnią się w zależności od typu zdarzenia relacji:
UTWORZONO
Utworzono strukturę
"relationUpdate" : { "type" : "CREATED", "subject" : "", "object" : "enterprises/project-id/structures/structure-id" }
Urządzenie zostało utworzone
"relationUpdate" : { "type" : "CREATED", "subject" : "enterprises/project-id/structures/structure-id", "object" : "enterprises/project-id/devices/device-id" }
Urządzenie zostało utworzone
"relationUpdate" : { "type" : "CREATED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
ZAKTUALIZOWANO
Urządzenie zostało przeniesione
"relationUpdate" : { "type" : "UPDATED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
USUNIĘTY
Usunięto strukturę
"relationUpdate" : { "type" : "DELETED", "subject" : "", "object" : "enterprises/project-id/structures/structure-id" }
Urządzenie zostało usunięte
"relationUpdate" : { "type" : "DELETED", "subject" : "enterprises/project-id/structures/structure-id", "object" : "enterprises/project-id/devices/device-id" }
Urządzenie zostało usunięte
"relationUpdate" : { "type" : "DELETED", "subject" : "enterprises/project-id/structures/structure-id/rooms/room-id", "object" : "enterprises/project-id/devices/device-id" }
Zdarzenia związane z relacjami nie są wysyłane, gdy:
- Pokój został usunięty
Zdarzenia związane z zasobami
Zdarzenie zasobu reprezentuje aktualizację związaną z danym zasobem. Mogą być reagowanie na zmiany wartość w polu cech, np. zmiana trybu termostatu. Może również reprezentować działanie na urządzeniu, które nie zmienia pola cech, na przykład naciśnięcia przycisku urządzenia.
Zdarzenie wygenerowane w odpowiedzi na zmianę wartości w polu właściwości zawiera
Obiekt traits
podobny do wywołania GET na urządzeniu:
Ładunek
{
"eventId" : "1ce720eb-9363-48f9-9b2e-f2344d2bf627",
"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"
]
}
Użyj osobiste dokumentacji cech, która zawiera informacje na temat formatu ładunku dla dowolnego zasobu zmiany pola cech. .
Zdarzenie generowane w odpowiedzi na działanie urządzenia, które nie zmienia pola cech, ma też atrybut
ładunek z obiektem resourceUpdate
, ale z obiektem events
zamiast obiektu traits
:
Ładunek
{ "eventId" : "273b6161-8c74-4253-9140-72998789dfca",
"timestamp" : "2019-01-01T00:00:01Z",
"resourceUpdate" : { "name" : "enterprises/project-id/devices/device-id", "events" : { "sdm.devices.events.CameraMotion.Motion
" : { "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...", "eventId" : "AUM1UrJN206B77r5FZbE8NQgBh...", } } } "userId" : "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
"eventThreadId" : "d67cd3f7-86a7-425e-8bb3-462f92ec9f59",
"eventThreadState" : "STARTED",
"resourceGroup" : [ "enterprises/project-id/devices/device-id" ] }
Te typy zdarzeń dotyczących zasobów są zdefiniowane w określonych cechach. Na przykład parametr Zdarzenie ruchu jest zdefiniowane w parametrze CameraMotion trait. Zobacz dokumentację każdej cechy aby poznać format ładunku dla tego typu zdarzeń zasobów.
Pola
Pole | Opis | Typ danych |
---|---|---|
eventId |
Unikalny identyfikator zdarzenia. | string Przykład: „273b6161-8c74-4253-9140-72998789dfca” |
timestamp |
Czas wystąpienia zdarzenia. | string Przykład: „2019-01-01T00:00:01Z” |
resourceUpdate |
Obiekt ze szczegółowymi informacjami o aktualizacji zasobu. | object |
userId |
Unikalny, zaciemniony identyfikator reprezentujący użytkownika. | string Przykład: „AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi” |
eventThreadId |
Unikalny identyfikator wątku wydarzenia. | string Przykład: „d67cd3f7-86a7-425e-8bb3-462f92ec9f59” |
eventThreadState |
Stan wątku wydarzenia. | string Wartości: „STARTED”, „UPDATED”, „ENDED” |
resourceGroup |
Obiekt wskazujący zasoby, które mogą mieć podobne aktualizacje do tego zdarzenia. Zasób samego zdarzenia (z obiektu resourceUpdate ) będzie zawsze obecny w tym obiekcie. |
object |
Więcej informacji o różnych zdarzeniach znajdziesz w sekcji Zdarzenia. typów zdarzeń i sposobu ich działania.
Powiadomienia, które można zaktualizować
Powiadomienia na podstawie zdarzeń dotyczących zasobów można zaimplementować w aplikacji, np. na urządzeniu z Androidem lub iOS. Aby zmniejszyć liczbę wysyłanych powiadomień, funkcja o nazwie mogą być wdrażane powiadomienia z możliwością aktualizacji, są aktualizowane o nowe informacje na podstawie kolejnych zdarzeń w ramach tego samego zdarzenia w wątku.Wybór wydarzeń obsługuje funkcje powiadomień z możliwością aktualizacji i są oznaczone jako
Można zaktualizować eventThreadId
. Użyj tej
które pozwala łączyć ze sobą poszczególne zdarzenia i aktualizować
powiadomienie wyświetlone użytkownikowi.
Wątek zdarzenia to nie to samo co sesja zdarzenia. Wątek wydarzenia. wskazuje zaktualizowany stan poprzedniego zdarzenia w tym samym wątku. sesja zdarzenia określa osobne zdarzenia, które są ze sobą powiązane. w przypadku danej sesji zdarzenia może istnieć wiele wątków.
Aby otrzymywać powiadomienia, dzielimy różne typy zdarzeń na różne .
Logika grupowania wątków i określania czasu jest obsługiwana przez Google i podlega można zmienić w każdej chwili. developer powinien zaktualizować powiadomienia na podstawie wątkami zdarzeń i sesjami udostępnianymi przez interfejs SDM API.
Stan wątku
Wydarzenia obsługujące powiadomienia z możliwością aktualizacji mają też parametr eventThreadState
pole, które wskazuje stan wątku zdarzenia w danym momencie. Ten
ma następujące wartości:
- STARTED – pierwsze wydarzenie w wątku wydarzenia.
- ZAKTUALIZOWANE – wydarzenie w trwającym wątku wydarzenia. W 1 wątku może być 0 lub więcej zdarzeń o tym stanie.
- ZAKOŃCZONE – ostatnie wydarzenie w wątku wydarzenia, które może być duplikatem ostatniego ZAKTUALIZOWANEGO wydarzenia w zależności od typu wątku.
W tym polu możesz śledzić postęp wątku wydarzenia oraz to, czy jest zakończono.
Filtrowanie zdarzeń
W niektórych przypadkach zdarzenia wykryte przez urządzenie mogą zostać odfiltrowane z publikacji do tematu SDM Pub/Sub. Takie działanie to filtrowanie zdarzeń. Filtrowanie zdarzeń pozwala uniknąć opublikowanie zbyt wielu podobnych wiadomości o wydarzeniu w krótkim czasie.
Wiadomość może na przykład zostać opublikowana w temacie SDM dla początkowego zdarzenia Motion. Inny powód a potem wiadomości dla ruchu są odfiltrowywane z publikacji przez określony czas. Po upływie tego okresu wiadomość o zdarzeniu tego typu może zostać opublikowana ponownie.
W aplikacji Google Home (GHA) zdarzenia, które zostały odfiltrowane dane będą nadal widoczne w historii zdarzeń urządzenia user. Jednakże nie generują powiadomienia aplikacji (nawet jeśli typ powiadomienia to ).
Każdy typ zdarzenia ma własną logikę filtrowania zdarzeń definiowaną przez Google i mogą ulec zmianie w dowolnym momencie. Ta logika filtrowania zdarzeń to niezależnie od wątku zdarzenia i logiki sesji.
Konta usługi
Konta usługi są zalecane do zarządzania interfejsami SDM API subskrypcji i wiadomości o wydarzeniach. konta usługi jest używane przez aplikację lub maszynie wirtualnej, a nie osobie, i ma własny, unikalny klucz konta.
Autoryzacja konta usługi w przypadku użycia interfejsu Pub/Sub API Dwuetapowa autoryzacja OAuth (2LO).
W ramach procesu autoryzacji dwuetapowej:
- developer żąda tokena dostępu za pomocą klucza usługi.
- developer używa tokena dostępu w wywołaniach interfejsu API.
Aby dowiedzieć się więcej o 2LO Google i o tym, jak ją skonfigurować, zobacz Używanie protokołu OAuth 2.0 na potrzeby połączeń między serwerami Aplikacje.
Autoryzacja
Konto usługi powinno być autoryzowane do używania z Interfejs API Pub/Sub:
- Włączanie Cloud Pub/Sub Interfejs API w Google Cloud.
- Utwórz konto usługi i klucz konta usługi zgodnie z opisem w sekcji Tworzenie konta usługi Zalecamy przypisanie mu tylko roli Subskrybent w Pub/Sub. Upewnij się, że: pobierz klucz konta usługi na komputer, który będzie używać Interfejs API Pub/Sub.
- Podaj dane uwierzytelniające (klucz konta usługi) na swoim
aplikacji, postępując zgodnie z instrukcjami na stronie w poprzedniej sekcji
lub ręcznie pobierz token dostępu przy użyciu
oauth2l
, jeśli chcą szybko przetestować dostęp do interfejsu API. - Użyj danych logowania konta usługi lub tokena dostępu z
Pub/Sub:
project.subscriptions
Interfejs API do pobierania i potwierdzania wiadomości.
OAuth2l
Google oauth2l
to narzędzie wiersza poleceń dla protokołu OAuth napisanego w języku Go. Zainstaluj
Mac lub Linux w Go.
- Jeśli nie masz aplikacji Go, najpierw ją pobierz i zainstaluj.
- Po zainstalowaniu Go zainstaluj aplikację
oauth2l
i dodaj jej lokalizację do urządzeniaPATH
zmienna środowiskowa:go install github.com/google/oauth2l@latest
export PATH=$PATH:~/go/bin
- Użyj
oauth2l
, aby uzyskać token dostępu dla interfejsu API, używając odpowiedniego Zakresy protokołu OAuth: Jeśli na przykład klucz usługi znajduje się pod adresemoauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
~/myServiceKey-eb0a5f900ee3.json
:oauth2l fetch --credentials ~/myServiceKey-eb0a5f900ee3.json --scope https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
ya29.c.Elo4BmHXK5...
Aby dowiedzieć się więcej, sprawdź README (oauth2l
).
i informacjami o nich.
Biblioteki klienta interfejsów API Google
Istnieje kilka bibliotek klienta dla interfejsów API Google, które korzystają z protokołu OAuth 2.0. Więcej informacji na ten temat znajdziesz w artykule Biblioteki klienta interfejsów API Google. w wybranym języku.
Jeśli używasz tych bibliotek razem z biblioteką Pub/Sub API, użyj funkcji te ciągi znaków dotyczące zakresu:
https://www.googleapis.com/auth/pubsub https://www.googleapis.com/auth/cloud-platform
Błędy
W związku z tym przewodnikiem mogą zostać zwrócone następujące kody błędów:
Komunikat o błędzie | RPC | Rozwiązywanie problemów |
---|---|---|
Zdjęcie z aparatu nie jest już dostępne do pobrania. | DEADLINE_EXCEEDED |
Obrazy zdarzeń wygasają po 30 sekundach od opublikowania zdarzenia. Pamiętaj, aby pobrać obraz przed wygaśnięciem ważności. |
Identyfikator zdarzenia nie należy do kamery. | FAILED_PRECONDITION |
Użyj prawidłowej wartości eventID zwróconej przez zdarzenie kamery. |
Zapoznaj się z informacjami na temat kodu błędu interfejsu API w przypadku: pełną listę kodów błędów interfejsu API.