Powiadomienia push

Właściwości wymagane

W przypadku każdego żądania watch musisz wypełnić te pola:

• Ciąg właściwości id jednoznacznie identyfikujący nowy kanał powiadomień w projekcie. Zalecamy użycie niepowtarzalnego identyfikatora uniwersalnego (UUID) lub innego podobnego unikalnego ciągu znaków. Maksymalna długość: 64 znaki.

  Ustawiona wartość identyfikatora jest odczytywana w nagłówku HTTP X-Goog-Channel-Id każdej wiadomości powiadomienia otrzymanej w związku z tym kanałem.

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

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

  Pamiętaj, że interfejs API pakietu 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 z podmiotem, który nie jest zgodny z docelową nazwą hosta.

Właściwości opcjonalne

W żądaniu watch możesz też określić te opcjonalne pola:

• 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żesz używać do różnych celów. Możesz na przykład użyć tokena, aby sprawdzić, czy każda wiadomość przychodząca pochodzi z kanału utworzonego przez Twoją aplikację – i upewnić się, że powiadomienie nie jest sfałszowana – lub do kierowania wiadomości do właściwego miejsca w aplikacji zgodnie z przeznaczeniem tego kanału. Maksymalna długość: 256 znaków.

  Token znajduje się w nagłówku HTTP X-Goog-Channel-Token w każdej wiadomości powiadomienia, którą aplikacja otrzyma z tego kanału.

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

  • Użyj rozszerzalnego formatu kodowania, 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 ustawiony na sygnatura czasowa uniksowa (w milisekundach) daty i godziny, kiedy interfejs API Admin SDK ma przestać wysyłać komunikaty z tego kanału powiadomień.

  Jeśli kanał ma określony czas ważności, jest on podawany jako wartość nagłówka HTTP X-Goog-Channel-Expiration (w formacie czytelnym dla człowieka) w każdej wiadomości powiadomienia o danym kanale, którą aplikacja otrzymuje.

Obejrzyj odpowiedź

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

Treść wiadomości odpowiedzi na zegarek zawiera informacje o nowo utworzonym kanale powiadomień, tak jak w tym przykładzie.

{
  "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 zwracane informacje obejmują też resourceId i resourceUri identyfikujące zasób, który chcesz obserwować na tym kanale powiadomień.

Zwrócone informacje możesz przekazywać do innych operacji związanych z kanałem powiadomień, na przykład wtedy, gdy chcesz przestać otrzymywać powiadomienia.

Więcej informacji o odpowiedzi znajdziesz w opisie metody watch dla zasobu Activities (Działania) w dokumentacji interfejsu API.

Synchronizuj wiadomość

Gdy utworzysz kanał powiadomień, aby oglądać zasób, interfejs Admin SDK API wysyła komunikat sync informujący o tym, że powiadomienia są uruchamiane. Wartość nagłówka HTTP X-Goog-Resource-State dla tych wiadomości to sync. Ze względu na problemy z czasem działania sieci możesz otrzymać komunikat sync jeszcze przed otrzymaniem odpowiedzi metody watch.

Powiadomienie sync możesz bez obaw zignorować, ale możesz też go użyć. Jeśli na przykład zdecydujesz, że nie chcesz zachować kanału, możesz użyć wartości X-Goog-Channel-ID i X-Goog-Resource-ID w wywołaniu, aby przestać otrzymywać powiadomienia. Możesz też użyć powiadomienia sync, aby przeprowadzić inicjalizację, aby przygotować się na późniejsze zdarzenia.

Poniżej znajdziesz format komunikatów sync, które interfejs API pakietu Admin SDK wysyła na Twój adres URL odbierania.

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 o wartości 1. Każde kolejne powiadomienie z tego kanału ma numer wiadomości większy od poprzedniego, przy czym numery wiadomości nie będą ułożone jedna po drugiej.

Odnów kanały powiadomień

Kanał powiadomień może mieć określony czas ważności, którego wartość zależy od żądania lub przez dowolne wewnętrzne limity interfejsu API pakietu Admin SDK lub wartości domyślne (stosowana jest bardziej restrykcyjna wartość). Czas wygaśnięcia kanału, jeśli taki istnieje, jest uwzględniany w informacjach zwracanych przez metodę watch jako sygnatura czasowa uniksowa (w milisekundach). Dodatkowo data i godzina wygaśnięcia są podawane (w formacie czytelnym dla człowieka) w każdej wiadomości powiadomienia, którą aplikacja otrzymuje dla danego kanału, w nagłówku HTTP X-Goog-Channel-Expiration.

Obecnie nie ma możliwości automatycznego odnowienia kanału powiadomień. Gdy kończy się okres ważności kanału, musisz go zastąpić nowym, wywołując metodę watch. Jak zawsze musisz użyć unikalnej wartości właściwości id nowego kanału. Pamiętaj, że w fazie „nakładanie się” może wystąpić sytuacja, gdy aktywne są 2 kanały powiadomień dotyczące tego samego zasobu.

Interpretowanie formatu wiadomości z powiadomieniem

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.

Wiadomości z powiadomieniami o działaniach 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ć, że wykonano operację, należy 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 500, 502, 503 lub 504, interfejs API Admin SDK ponawia próbę z wykładniczym ponownym opóźnieniem. Każdy inny kod stanu jest uważany za błąd wiadomości.

Omówienie zdarzeń powiadomień interfejsu API pakietu Admin SDK

Ta sekcja zawiera szczegółowe informacje o wiadomościach z powiadomieniami, które możesz otrzymywać, gdy używasz powiadomień push za pomocą interfejsu API Admin SDK.

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

• admin
• kalendarz
• dysk
• grupy
• login
• komórka
• saml
• token
• user_accounts