Powiadomienia push

Właściwości wymagane

W każdym żądaniu watch musisz wypełnić te pola:

• Ciąg znaków właściwości id, który jednoznacznie określa tę właściwość nowy kanał powiadomień w projekcie. Zalecamy użycie uniwersalny identyfikator (UUID) lub podobny jest unikalny ciąg znaków. Maksymalna długość: 64 znaki.

  Ustawiona wartość identyfikatora jest odczytywana ponownie Nagłówek HTTP X-Goog-Channel-Id każdego powiadomienia jaką wiadomość otrzymujesz na temat 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 i odpowiada na powiadomienia z tego kanału powiadomień. To jest adresu URL wywołania zwrotnego webhooka i musi on używać protokołu HTTPS.

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

  • podpisane samodzielnie,
  • podpisane przez niezaufane źródło,
  • unieważnione.
  • Certyfikaty z tematem, który nie pasuje do celu nazwa hosta.

Właściwości opcjonalne

Te opcjonalne pola możesz też określić za pomocą Prośba o środki (watch):

• właściwość token, która określa dowolny ciąg znaków. do użycia jako token kanału. Możesz użyć kanału powiadomień do różnych celów. Na przykład możesz użyć atrybutu token do potwierdzenia, że każda przychodząca wiadomość pochodzi z kanału, utworzona aplikacja – by upewnić się, że powiadomienie nie jest wysyłane sfałszowana – lub aby skierować wiadomość do właściwego miejsca docelowego w: zgodnie z przeznaczeniem kanału. Maksymalna długość: 256 znaków.

  Token znajduje się w sekcji Nagłówek HTTP X-Goog-Channel-Token w każdym powiadomieniu wyświetlany w aplikacji dla tego kanału.

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

  • Użyj możliwego formatu kodowania, takiego jak zapytanie 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, o której interfejs API Admin SDK ma zaprzestać wysyłania wiadomości z tego kanału powiadomień.

  Jeśli kanał ma datę ważności, jest on podany jako wartość. nagłówka HTTP X-Goog-Channel-Expiration (w formacie czytelnym dla człowieka) ) w każdej wiadomości z powiadomieniem, otrzymuje tyle zgłoszeń dotyczących tego kanału.

Obejrzyj odpowiedź

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

Treść wiadomości w odpowiedzi zegarka zawiera informacje o kanału powiadomień, tak jak pokazano to 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 przesłanych w ramach żądania parametr zwrócone informacje obejmują również resourceId i resourceUri, aby zidentyfikować zasób, który jest na nim obserwowany kanału powiadomień.

Możesz przekazać zwrócone informacje do innego kanału powiadomień operacji, na przykład gdy chcesz przestać otrzymywać powiadomienia.

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

Zsynchronizuj wiadomość

Po utworzeniu kanału powiadomień, aby oglądać zasób, Interfejs API Admin SDK wysyła komunikat sync, aby wskazać, że powiadomienia. Protokół HTTP X-Goog-Resource-State wartość nagłówka tych wiadomości to sync. Ze względu na sieć problemy z czasem, możesz otrzymać komunikat sync jeszcze przed otrzymaniem odpowiedzi metody watch.

Możesz bezpiecznie zignorować powiadomienie sync, ale możesz go użyć. Jeśli na przykład nie chcesz przechowywać kanału, możesz korzystać z funkcji X-Goog-Channel-ID i X-Goog-Resource-ID wartości w wywołaniu do wyłączyć otrzymywanie powiadomień. Możesz też użyć usługi Powiadomienie sync dotyczące inicjalizacji w celu przygotowania późniejszych wydarzeń.

Format komunikatów sync, do których interfejs Admin SDK API wysyła Twój adres URL odbierania 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 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

Synchronizowane wiadomości zawsze mają żądanie HTTP X-Goog-Message-Number 1. Każde kolejne powiadomienie z tego kanału numer wiadomości jest większy niż poprzedni, mimo że komunikat liczby nie występują po sobie.

Odnawianie kanałów powiadomień

Kanał powiadomień może mieć czas wygaśnięcia i podaną wartość określane na podstawie żądania lub wewnętrznych limitów interfejsu API Admin SDK lub wartości domyślne (stosowana jest wartość bardziej restrykcyjna). Wygaśnięcie kanału Godzina (jeśli go występuje), jest dołączana jako sygnatura czasowa uniksowa (w milisekundach) w informacjach zwracanych przez metodę watch. Dodatkowo data i godzina wygaśnięcia są podane (w formacie czytelnym dla człowieka) w każdym powiadomienie dotyczące tego kanału, które Twoja aplikacja otrzyma w Nagłówek HTTP X-Goog-Channel-Expiration.

Obecnie nie można automatycznie odnowić kanału powiadomień. Kiedy kanał wkrótce wygaśnie. Musisz zastąpić go nowym, dzwoniąc metodę watch. Jak zawsze, musisz użyć unikalnej wartości dla argumentu właściwość id nowego kanału. Pamiętaj, że istnieje możliwość aby „pokrywać się” okresu, w którym dwa kanały powiadomień są aktywne takie same zasoby.

Interpretowanie formatu wiadomości powiadomienia

Wszystkie powiadomienia zawierają zestaw nagłówków HTTP X-Goog- prefiksy. 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 oznaczyć powodzenie, można wyświetlić dowolny z tych kodów stanu: 200, 201, 202, 204 lub 102.

Jeśli Twoja usługa używa biblioteki klienta interfejsów API Google i zwraca 500, 502, 503 lub 504, interfejs API Admin SDK ponawia próby z wykładniczym czasem ponowienia. Każdy inny kod stanu zwrotu jest uważany za niepowodzenie otrzymania wiadomości.

Omówienie zdarzeń powiadomień interfejsu Admin SDK API

Ta sekcja zawiera szczegółowe informacje na temat powiadomień, które możesz w przypadku korzystania z 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:

• administrator
• kalendarz
• samochodem
• grupy
• login
• komórka
• SAML
• token
• user_accounts