Notifiche push

Proprietà obbligatorie

Per ogni richiesta di tipo watch, devi fornire i seguenti campi:

• Una stringa di proprietà id che identifica in modo univoco questo nuovo canale di notifica all'interno del progetto. Ti consigliamo di utilizzare un identificatore univoco universale (UUID) o qualsiasi stringa univoca simile. Lunghezza massima: 64 caratteri.

  Il valore ID impostato viene riportato nell'X-Goog-Channel-Id intestazione HTTP di ogni messaggio di notifica che ricevi per questo canale.

• Una stringa di proprietà type impostata sul valore web_hook.

• Una stringa di proprietà address impostata sull'URL che ascolta e risponde alle notifiche per questo canale di notifica. Questo è l'URL di callback del webhook e deve utilizzare HTTPS.

  Tieni presente che l'API Admin SDK è in grado di inviare notifiche a questo indirizzo HTTPS solo se sul tuo server web è installato un certificato SSL valido. I certificati non validi includono:

  • Certificati autofirmati.
  • Certificati firmati da una fonte non attendibile.
  • Certificati revocati.
  • Certificati con un oggetto che non corrisponde al nome host di destinazione.

Proprietà facoltative

Puoi anche specificare questi campi facoltativi con la richiesta watch:

• Una proprietà token che specifica un valore di stringa arbitrario da utilizzare come token del canale. Puoi utilizzare i token del canale di notifica per vari scopi. Ad esempio, puoi utilizzare il token per verificare che ogni messaggio in arrivo sia per un canale creato dall'applicazione (per garantire che la notifica non sia oggetto di spoofing) o per indirizzare il messaggio alla destinazione corretta all'interno dell'applicazione in base allo scopo di questo canale. Lunghezza massima: 256 caratteri.

  Il token è incluso nell'X-Goog-Channel-Token intestazione HTTP di ogni messaggio di notifica che la tua applicazione riceve per questo canale.

  Se utilizzi token dei canali di notifica, ti consigliamo di:

  • Utilizza un formato di codifica estensibile, ad esempio i parametri di query dell'URL. Esempio: forwardTo=hr&createdBy=mobile

  • Non includere dati sensibili come token OAuth.

• Una stringa di proprietà expiration impostata su un timestamp Unix (in millisecondi) della data e dell'ora in cui vuoi che l'API SDK Admin smetta di inviare messaggi per questo canale di notifica.

  Se un canale ha una scadenza, questa viene inclusa come valore dell'intestazione HTTP X-Goog-Channel-Expiration (in formato leggibile) in ogni messaggio di notifica che l'applicazione riceve per questo canale.

Risposta dall'orologio

Se la richiesta watch crea correttamente un canale di notifica, viene restituito un codice di stato HTTP 200 OK.

Il corpo del messaggio della risposta dello smartwatch fornisce informazioni sul canale di notifica che hai appena creato, come mostrato nell'esempio seguente.

{
  "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.
}

Oltre alle proprietà inviate nell'ambito della richiesta, le informazioni restituite includono anche resourceId e resourceUri per identificare la risorsa guardata su questo canale di notifica.

Puoi passare le informazioni restituite ad altre operazioni del canale di notifica, ad esempio quando vuoi interrompere la ricezione delle notifiche.

Per ulteriori dettagli sulla risposta, consulta il metodo watch per la risorsa Attività nel riferimento all'API.

Sincronizza messaggio

Dopo aver creato un canale di notifica per monitorare una risorsa, l'API Admin SDK invia un messaggio sync per indicare che le notifiche stanno iniziando. Il valore dell'intestazione HTTP X-Goog-Resource-State per questi messaggi è sync. A causa di problemi di temporizzazione della rete, è possibile ricevere il messaggio sync anche prima di ricevere la risposta del metodo watch.

Puoi ignorare la notifica sync, ma puoi anche usarla. Ad esempio, se decidi di non mantenere il canale, puoi utilizzare i valori X-Goog-Channel-ID e X-Goog-Resource-ID in una chiamata per smettere di ricevere notifiche. Puoi anche utilizzare la notifica sync per eseguire alcune operazioni di inizializzazione e prepararti per gli eventi successivi.

Di seguito è riportato il formato dei messaggi sync inviati dall'API SDK Admin al tuo URL di ricezione.

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

I messaggi di sincronizzazione hanno sempre un valore dell'intestazione HTTP X-Goog-Message-Number uguale a 1. Ogni notifica successiva per questo canale ha un numero di messaggio maggiore di quello precedente, anche se i numeri dei messaggi non saranno sequenziali.

Rinnova i canali di notifica

Un canale di notifica può avere una data e un'ora di scadenza, con un valore determinato dalla tua richiesta o da eventuali limiti o valori predefiniti interni dell'API Admin SDK (viene utilizzato il valore più restrittivo). La data e l'ora di scadenza del canale, se esistenti, sono incluse come timestamp Unix (in millisecondi) nelle informazioni restituite dal metodo watch. Inoltre, la data e l'ora di scadenza sono incluse (in un formato leggibile) in ogni messaggio di notifica che la tua applicazione riceve per questo canale nell'intestazione HTTP X-Goog-Channel-Expiration.

Al momento non esiste un modo automatico per rinnovare un canale di notifica. Quando un canale è prossimo alla scadenza, devi sostituirlo con uno nuovo chiamando il metodo watch. Come sempre, devi utilizzare un valore univoco per la proprietà id del nuovo canale. Tieni presente che è probabile che ci sia un periodo di "sovrapposizione" in cui sono attivi i due canali di notifica per la stessa risorsa.

Interpreta il formato del messaggio di notifica

Tutti i messaggi di notifica includono un insieme di intestazioni HTTP con prefisso X-Goog-. Alcuni tipi di notifiche possono anche includere un corpo del messaggio.

I messaggi di notifica per le attività contengono le seguenti informazioni nel corpo della richiesta:

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

Risposta alle notifiche

Per indicare il successo, puoi restituire uno dei seguenti codici di stato: 200, 201, 202, 204 o 102.

Se il tuo servizio utilizza la libreria client dell'API di Google e restituisce 500, 502, 503 o 504, l'API SDK Admin riprova con il backoff esponenziale. Ogni altro codice di stato del reso è considerato un errore del messaggio.

Informazioni sugli eventi di notifica dell'API SDK Admin

Questa sezione fornisce dettagli sui messaggi di notifica che puoi ricevere quando utilizzi le notifiche push con l'API SDK Admin.

Le notifiche push dell'API Reports contengono due tipi di messaggi: messaggi di sincronizzazione e notifiche di eventi. Il tipo di messaggio è indicato nell'intestazione HTTP X-Goog-Resource-State. I possibili valori per le notifiche di eventi sono gli stessi del metodo activities.list. Ogni applicazione ha eventi unici:

• admin
• calendario
• guidare
• groups
• login
• dispositivo mobile
• saml
• token
• user_accounts