Ta strona została przetłumaczona przez Cloud Translation API.

Wydarzenia

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 tym, jak działa 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

Po włączeniu wydarzeń w przypadku 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" : "06f4651c-8fc0-4525-9138-1662ffe268b3",
  "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: „6c0031ac-b979-4622-858b-e2a4e38655ef”
`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" : "172f8070-f7c7-42f7-9110-760c6049fc30",
  "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" : "dccde63e-29b8-49d7-ae64-198450bae2bf",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "events" : {
      "sdm.devices.events.CameraMotion.Motion" : {
        "eventSessionId" : "CjY5Y3VKaTZwR3o4Y19YbTVfMF...",
        "eventId" : "Bw3CN4TTI2FtYtTsvRypvsfSXu...",
      }
    }
  }
  "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: „dccde63e-29b8-49d7-ae64-198450bae2bf”
`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: „ROZPOCZĘTO”, „ZAKTUALIZOWANE”, „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ć w dokumentacji. Te wydarzenia mają w ładunkach dodatkowe pole o nazwie 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. To zachowanie 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ądzenia PATH 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:

oauth2l fetch --credentials path-to-service-key.json --scope https://www.googleapis.com/auth/pubsub
https://www.googleapis.com/auth/cloud-platform

Jeśli na przykład klucz usługi znajduje się pod adresem ~/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.