Notifiche push

Proprietà obbligatorie

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

• Una stringa della proprietà id che identifica in modo univoco nuovo canale di notifica all'interno del tuo progetto. È consigliabile utilizzare Un identificatore univoco universale (UUID) o simile stringa univoca. Lunghezza massima: 64 caratteri.

  Il valore ID impostato viene ripreso nel campo Intestazione HTTP X-Goog-Channel-Id di ogni notifica che ricevi per questo canale.

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

• Una stringa della 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 SDK Admin è in grado di inviare notifiche a questo indirizzo HTTPS solo se è installato un certificato SSL valido sul tuo server web. I certificati non validi includono:

  • Certificati autofirmati.
  • Certificati firmati da una fonte non attendibile.
  • Certificati revocati.
  • Certificati con un oggetto che non corrisponde alla destinazione dell'host.

Proprietà facoltative

Puoi anche specificare questi campi facoltativi Richiesta di watch:

• Una proprietà token che specifica una stringa arbitraria da utilizzare come token del canale. Puoi usare il canale di notifica di token per vari scopi. Ad esempio, puoi utilizzare per verificare che ogni messaggio in arrivo sia destinato a un canale dell'applicazione creata, per assicurarti che la notifica falsificato o per indirizzare il messaggio alla destinazione corretta la tua applicazione in base allo scopo di questo canale. Lunghezza massima: 256 caratteri.

  Il token è incluso nel X-Goog-Channel-Token intestazione HTTP in ogni notifica che la tua applicazione riceve per il canale.

  Se utilizzi i token del canale di notifica, ti consigliamo di:

  • Utilizza un formato di codifica estensibile, come la query URL parametri. Esempio: forwardTo=hr&createdBy=mobile

  • Non includere dati sensibili come i token OAuth.

  di Gemini Advanced.

• Una stringa della proprietà expiration impostata su un Timestamp Unix (in millisecondi) della data e dell'ora in cui vuoi che l'API SDK Admin interrompi l'invio di 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 ricevute dall'applicazione per questo canale.

Guarda la risposta

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

Il corpo del messaggio della risposta dell'orologio fornisce informazioni sul canale di notifica appena creato, come mostrato nell'esempio riportato di seguito.

{
  "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, i campi le informazioni restituite includono anche resourceId e resourceUri per identificare la risorsa guardata su questo canale di notifica.

Puoi passare le informazioni restituite a un altro canale di notifica operazioni, come quando interrompi la ricezione notifiche.

Per ulteriori dettagli sulla risposta, consulta watch per la risorsa Activities nel riferimento API.

Sincronizza messaggio

Dopo aver creato un canale di notifica per osservare una risorsa, L'API SDK Admin invia un messaggio sync per indicare che le notifiche vengono avviate. HTTP X-Goog-Resource-State il valore dell'intestazione per questi messaggi è sync. A causa della rete problemi di tempo, puoi ricevere il messaggio sync anche prima di ricevere la risposta del metodo watch.

Puoi ignorare la notifica di sync, ma puoi lo usi. Ad esempio, se decidi di non voler più mantenere il canale, puoi usare X-Goog-Channel-ID e Valori di X-Goog-Resource-ID in una chiamata a interrompere la ricezione delle notifiche. Puoi utilizzare anche Notifica sync per eseguire alcune operazioni di inizializzazione per prepararsi per gli eventi successivi.

Il formato dei messaggi sync a cui invia l'API SDK Admin l'URL di destinazione è riportato di seguito.

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 HTTP X-Goog-Message-Number valore dell'intestazione 1. Ogni notifica successiva per questo canale contiene un numero di messaggio maggiore del precedente, sebbene il messaggio i numeri non saranno sequenziali.

Rinnova canali di notifica

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

Al momento, non è possibile rinnovare automaticamente un canale di notifica. Quando un canale è prossimo alla scadenza, devi sostituirlo con uno nuovo richiamando il metodo watch. Come sempre, devi utilizzare un valore univoco per la proprietà id del nuovo canale. Tieni presente che è probabile in modo che sia una "sovrapposizione" periodo di tempo in cui i due canali di notifica sono attive le stesse risorse.

Interpretare il formato dei messaggi di notifica

Tutti i messaggi di notifica includono un insieme di intestazioni HTTP con X-Goog- prefissi. Alcuni tipi di notifiche possono includere anche 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 che l'operazione è andata a buon fine, puoi restituire uno dei seguenti codici di stato: 200, 201, 202, 204 o 102.

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

Informazioni sugli eventi di notifica dell'API Admin SDK

Questa sezione fornisce dettagli sui messaggi di notifica che puoi quando si utilizzano 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 valori possibili per le notifiche di eventi sono gli stessi del metodo activities.list. Ogni applicazione ha eventi univoci:

• amministratore
• calendario
• guidare
• gruppi
• login
• dispositivo mobile
• saml
• token
• user_accounts