Powiadomienia push

Właściwości wymagane

W przypadku każdego żądania watch musisz podać te pola:

• Unikalny ciąg znaków właściwości id, który jednoznacznie identyfikuje ten nowy kanał powiadomień w Twoim projekcie. Zalecamy użycie uniwersalnego identyfikatora (UUID) lub podobnego unikalnego ciągu znaków. Maksymalna długość: 64 znaki.

  Ustawiona przez Ciebie wartość identyfikatora jest odzwierciedlana w nagłówku HTTP X-Goog-Channel-Id każdego powiadomienia, które otrzymujesz z tego kanału.

• Ciąg znaków właściwości type ustawiony na wartość web_hook.

• ciąg znaków właściwości address ustawiony na adres URL, który nasłuchuje i odpowiada na powiadomienia dla tego kanału powiadomień. To jest adres URL wywołania zwrotnego webhooka, który musi używać protokołu HTTPS.

  Pamiętaj, że interfejs Admin SDK może wysyłać powiadomienia na ten adres HTTPS tylko wtedy, gdy na serwerze WWW jest zainstalowany prawidłowy certyfikat SSL. Nie prawidłowe certyfikaty to między innymi:

  • podpisane samodzielnie,
  • podpisane przez niezaufane źródło,
  • unieważnione.
  • Certyfikaty, których podmiot nie pasuje do docelowej nazwy hosta.

Właściwości opcjonalne

W prośbie watch możesz też podać te pola opcjonalne:

• Właściwość token, która określa dowolną wartość ciągu znaków do użycia jako token kanału. Tokenów kanału powiadomień można używać do różnych celów. Możesz na przykład użyć tokena, aby sprawdzić, czy każda przychodząca wiadomość jest przeznaczona do kanału utworzonego przez Twoją aplikację (aby mieć pewność, że powiadomienie nie jest sfałszowane) lub przekierować wiadomość do odpowiedniego miejsca w aplikacji na podstawie celu tego kanału. Maksymalna długość: 256 znaków.

  Token znajduje się w nagłówku HTTP X-Goog-Channel-Token w każdym powiadomieniu, które aplikacja otrzymuje dla tego kanału.

  Jeśli używasz tokenów kanału powiadomień, zalecamy:

  • Użyj formatu kodowania umożliwiającego rozszerzanie, np. parametrów zapytania w adresie URL. Przykład: forwardTo=hr&createdBy=mobile

  • Nie podawaj danych wrażliwych, takich jak tokeny OAuth.

• Ciąg właściwości expiration z sygnaturą czasową uniksową (w milisekundach) określającą datę i godzinę, kiedy interfejs API Admin SDK ma przestać wysyłać wiadomości do tego kanału powiadomień.

  Jeśli kanał ma czas ważności, jest on uwzględniany jako wartość nagłówka HTTP X-Goog-Channel-Expiration (w czytelnym dla człowieka formacie) w każdej wiadomości z powiadomieniem, którą aplikacja otrzymuje z tego kanału.

Odpowiedź

Jeśli żądanie watch tworzy kanał powiadomień, zwraca kod stanu HTTP 200 OK.

Treść odpowiedzi na obejrzenie filmu zawiera informacje o korzystaniu z konkretnego kanału powiadomień, jak pokazano w przykładzie poniżej.

{
  "kind": "api#channel",
  "id": "reportsApiId", // ID you specified for this channel.
  "resourceId": "o3hgv1538sdjfh", // ID of the watched resource.
  "resourceUri": "https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName", // Version-specific ID of the watched resource.
  "token": "target=myApp-myFilesChannelDest", // Present only if one was provided.
  "expiration": 3600, // Actual expiration time as Unix timestamp (in ms), if applicable.
}

Oprócz właściwości wysłanych w ramach żądania zwrócone informacje zawierają również atrybuty resourceId i resourceUri identyfikujące zasób obserwowany w tym kanale powiadomień.

Możesz przekazać zwrócone informacje do innych operacji na kanale powiadomień, na przykład gdy chcesz zatrzymać otrzymywanie powiadomień.

Więcej informacji o odpowiedzi znajdziesz w metodie watch dla zasobu Activities w przewodniku po interfejsie API.

Synchronizuj wiadomość

Po utworzeniu kanału powiadomień umożliwiającego oglądanie zasobu interfejs API Admin SDK wysyła komunikat sync, aby wskazać, że powiadomienia się uruchamiają. Wartość nagłówka HTTP X-Goog-Resource-State tych wiadomości to sync. Ze względu na problemy z czasem w sieci możliwe jest, że wiadomość sync zostanie wysłana, zanim otrzymasz odpowiedź metody watch.

Możesz bezpiecznie zignorować powiadomienie sync, ale możesz też z niego skorzystać. Jeśli na przykład zdecydujesz się nie zachować kanału, możesz użyć wartości X-Goog-Channel-ID i X-Goog-Resource-ID w wywołaniu, aby zatrzymać otrzymywanie powiadomień. Możesz też użyć powiadomienia sync do przeprowadzenia inicjowania, aby przygotować się na późniejsze zdarzenia.

Poniżej przedstawiamy format wiadomości sync wysyłanych przez interfejs Admin SDK do adresu URL odbierającego.

POST https://mydomain.com/notifications // Your receiving URL.
X-Goog-Channel-ID: channel-ID-value
X-Goog-Channel-Token: channel-token-value
X-Goog-Channel-Expiration: expiration-date-and-time // In human-readable format. Present only if the channel expires.
X-Goog-Resource-ID: identifier-for-the-watched-resource
X-Goog-Resource-URI: version-specific-URI-of-the-watched-resource
X-Goog-Resource-State: sync
X-Goog-Message-Number: 1

Wiadomości synchronizacji mają zawsze wartość nagłówka HTTP X-Goog-Message-Number 1. Każde kolejne powiadomienie na tym kanale ma numer większy od poprzedniego, ale numery wiadomości nie będą uporządkowane.

Odnawianie kanałów powiadomień

Kanał powiadomień może mieć czas wygaśnięcia, którego wartość jest określona na podstawie Twojego żądania lub dowolnych wewnętrznych limitów bądź wartości domyślnych interfejsu Admin SDK API (stosowana jest bardziej restrykcyjna wartość). Czas wygaśnięcia kanału, jeśli jest podany, jest podawany jako sygnatura czasowa uniksowa (w milisekundach) w informacjach zwracanych przez metodę watch. Dodatkowo data i godzina wygaśnięcia (w czytelnym dla człowieka formacie) są zawarte w każdej wiadomości z powiadomieniem, którą aplikacja otrzymuje dla tego kanału w nagłówku HTTP X-Goog-Channel-Expiration.

Obecnie nie ma automatycznego sposobu odnawiania kanału powiadomień. Gdy kanał zbliża się do daty wygaśnięcia, musisz go zastąpić nowym, wywołując metodę watch. Jak zawsze, w przypadku właściwości id nowego kanału musisz użyć unikalnej wartości. Pamiętaj, że prawdopodobnie będzie okres „nakładania się”, gdy 2 kanały powiadomień dla tego samego zasobu będą aktywne.

Interpretowanie formatu powiadomienia

Wszystkie wiadomości z powiadomieniami zawierają zestaw nagłówków HTTP z prefiksami X-Goog-. Niektóre typy powiadomień mogą też zawierać treść wiadomości.

Komunikaty z powiadomieniami o aktywności zawierają w treści żądania te informacje:

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 0
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 398348u3tu83ut8uu38
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret08u3rv24htgh289g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/userKey/applications/applicationName
X-Goog-Resource-State:  eventName
X-Goog-Message-Number: 10

{
  "kind": "admin#reports#activity",
  "id": {
    "time": datetime,
    "uniqueQualifier": long,
    "applicationName": string,
    "customerId": string
  },
  "actor": {
    "callerType": string,
    "email": string,
    "profileId": long
  },
  "ownerDomain": string,
  "ipAddress": string,
  "events": [
    {
      "type": string,
      "name": string,
      "parameters": [
        {
          "name": string,
          "value": string,
          "intValue": long,
          "boolValue": boolean
        }
      ]
    }
  ]
}

POST https://mydomain.com/notifications // Your receiving URL.
Content-Type: application/json; utf-8
Content-Length: 596
X-Goog-Channel-ID: reportsApiId
X-Goog-Channel-Token: 245t1234tt83trrt333
X-Goog-Channel-Expiration: Tue, 29 Oct 2013 20:32:02 GMT
X-Goog-Resource-ID:  ret987df98743md8g
X-Goog-Resource-URI: https://admin.googleapis.com/admin/reports/v1/activity/users/all/applications/admin?alt=json
X-Goog-Resource-State:  CREATE_USER
X-Goog-Message-Number: 23

{
  "kind": "admin#reports#activity",
  "id": {
    "time": "2013-09-10T18:23:35.808Z",
    "uniqueQualifier": "-0987654321",
    "applicationName": "admin",
    "customerId": "ABCD012345"
  },
  "actor": {
    "callerType": "USER",
    "email": "admin@example.com",
    "profileId": "0123456789987654321"
  },
  "ownerDomain": "apps-reporting.example.com",
  "ipAddress": "192.0.2.0",
  "events": [
    {
      "type": "USER_SETTINGS",
      "name": "CREATE_USER",
      "parameters": [
        {
          "name": "USER_EMAIL",
          "value": "liz@example.com"
        }
      ]
    }
  ]
}

Odpowiedz na powiadomienia

Aby wskazać powodzenie, możesz zwrócić dowolny z tych kodów stanu: 200, 201, 202, 204 lub 102.

Jeśli Twoja usługa korzysta z biblioteki klienta interfejsu API Google i zwraca wartości 500,502, 503 lub 504, interfejs API Admin SDK próbuje ponownie, stosując eksponencjalne wycofanie. Każdy inny kod stanu zwrotu jest uważany za niepowodzenie dostarczenia wiadomości.

Informacje o zdarzeniach powiadomień interfejsu Admin SDK API

Ta sekcja zawiera szczegółowe informacje na temat powiadomień, które możesz otrzymywać, gdy używasz powiadomień push za pomocą interfejsu API Admin SDK.

Powiadomienia push interfejsu Reports API zawierają 2 typy wiadomości: wiadomości o synchronizacji i powiadomienia o wydarzeniach. Typ wiadomości jest podany w nagłówku HTTP X-Goog-Resource-State. Możliwe wartości powiadomień o zdarzeniach są takie same jak w przypadku metody activities.list. Każda aplikacja ma unikalne zdarzenia:

• admin
• kalendarz
• Dysk
• grup
• login
• komórka
• saml
• token
• user_accounts