Powiadomienia push

Właściwości wymagane

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

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

  Ustawiona wartość identyfikatora jest odczytywana w nagłówku X-Goog-Channel-Id każdej wiadomości z powiadomieniem dotyczącej tego kanału.

• Ciąg 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 powiadomień z tego kanału powiadomień i odpowiada na nie. To jest adres URL wywołania zwrotnego webhooka i musi używać protokołu HTTPS.

  Pamiętaj, że interfejs Admin SDK API będzie mógł wysyłać powiadomienia na ten adres HTTPS tylko wtedy, gdy na serwerze WWW jest zainstalowany ważny certyfikat SSL. Nie prawidłowe certyfikaty to między innymi:

  • podpisane samodzielnie,
  • podpisane przez niezaufane źródło,
  • unieważnione.
  • Certyfikaty o charakterze zgodnym z nazwą hosta docelowego.

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, który ma być używany jako token kanału. Tokenów kanału powiadomień można używać do różnych celów. Na przykład możesz użyć tokena, aby sprawdzić, czy każda wiadomość przychodzących pochodzi z kanału utworzonego przez aplikację, dzięki czemu powiadomienie nie będzie sfałszowane, lub aby kierować wiadomość do odpowiedniego miejsca docelowego 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 każdej wiadomości z powiadomieniem, którą otrzymuje Twój kanał.

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

  • Użyj elastycznego formatu kodowania, takiego jak parametry zapytania z adresu 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 Unix (w ms) daty i godziny, kiedy interfejs Admin SDK API ma przestać wysyłać wiadomości dla tego kanału powiadomień.

  Jeśli czas trwania kanału jest określony, zostanie on uwzględniony jako wartość nagłówka HTTP X-Goog-Channel-Expiration (tym razem w postaci zrozumiałej dla człowieka) w każdym powiadomieniu wysyłanym do aplikacji przez ten kanał.

Obserwuj odpowiedź

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

Treść wiadomości z odpowiedzi na zegarek zawiera informacje o stworzeniu właśnie utworzonego kanału powiadomień (przykład 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, zwracane informacje obejmują też resourceId i resourceUri, które wskazują zasób wyświetlany w tym kanale powiadomień.

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

Więcej informacji o odpowiedzi znajdziesz w metodzie watch dotyczącej zasobu Aktywności w dokumentacji API.

Synchronizuj wiadomość

Gdy utworzysz nowy kanał powiadomień, żeby obejrzeć zasób, interfejs Admin SDK API wyśle komunikat sync z informacją o rozpoczęciu powiadomień. Wartość nagłówka HTTP X-Goog-Resource-State tych wiadomości to sync. Ze względu na problemy z czasem sieciowym może się zdarzyć, że otrzymasz wiadomość sync, jeszcze zanim otrzymasz odpowiedź metody watch.

Możesz zignorować powiadomienie sync, ale możesz z niego skorzystać. Jeśli na przykład postanowisz nie zachowywać kanału, możesz użyć wartości X-Goog-Channel-ID i X-Goog-Resource-ID w wywołaniu, aby wyłączyć powiadomienia. Możesz też użyć powiadomienia sync, aby przeprowadzić inicjację na potrzeby przyszłych zdarzeń.

Format wiadomości sync wysyłanych przez interfejs Admin SDK API na adres docelowy jest widoczny poniżej.

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 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 równą 1. Każde kolejne powiadomienie z tego kanału będzie mieć numer wiadomości wyższy od poprzedniego, ale numery wiadomości nie będą sekwencyjne.

Odnawianie kanałów powiadomień

Kanał powiadomień może mieć okres ważności, którego wartość jest określana na podstawie żądania albo wewnętrznych limitów lub domyślnych interfejsów Admin SDK API (używana jest bardziej restrykcyjna wartość). Czas wygaśnięcia kanału (jeśli go ma) jest podany jako sygnatura czasowa Unix (w ms) w informacjach zwracanych przez metodę watch. Dodatkowo data i godzina wygaśnięcia (w formacie czytelnym dla człowieka) jest podana w nagłówku HTTP X-Goog-Channel-Expiration w powiadomieniach, które aplikacja otrzymuje w związku z danym kanałem.

Obecnie nie ma możliwości automatycznego odnawiania kanału powiadomień. Gdy zbliża się data wygaśnięcia ważności kanału, musisz utworzyć nowy, wywołując metodę watch. Jak zawsze musisz użyć unikalnej wartości właściwości id nowego kanału. Pamiętaj, że okres aktywności obu kanałów powiadomień dotyczących tego samego zasobu może być okresu.

Omówienie formatu wiadomości z powiadomieniem

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

Treść powiadomień dotyczących działań zawiera te informacje w treści żądania:

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"
        }
      ]
    }
  ]
}

Odpowiadanie na powiadomienia

Aby wskazać, że projekt zakończył się powodzeniem, możesz użyć dowolnego z tych kodów stanu: 200, 201, 202, 204 lub 102.

Jeśli Twoja usługa używa biblioteki klienta interfejsu API Google& Każdy inny kod stanu zwrotu jest uznawany za niepowodzenie wiadomości.

Zdarzenia dotyczące powiadomień w interfejsie Admin SDK API

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

Powiadomienia push w interfejsie Reports API zawierają 2 rodzaje wiadomości: synchronizację 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 w przypadku metody activities.list. Każda aplikacja ma unikalne zdarzenia:

• administrator
• kalendarz
• samochodem
• grupy
• login
• komórka
• saml
• token
• konta_użytkownika