Riferimento API Graph

Panoramica

L'API Graph per Workplace consente di immettere ed estrarre dati da Workplace in modo programmatico. Si tratta di un'API di basso livello basata su HTTP che è possibile utilizzare per effettuare query sui dati relativi agli oggetti in un grafico Workplace.

L'API Graph ha preso il nome dall'idea di un modello di dati del grafico, in cui gli oggetti sono rappresentati da nodi e uniti lungo i segmenti. A livello di API, è la modalità di accesso delle app alle informazioni su Workplace. L'API Graph per Workplace consente un sottoinsieme di funzionalità dell'API Graph per Facebook. Questa funzionalità è limitata alle interazioni con una community di Workplace e può differire in alcuni casi per prestazioni o usabilità migliori.

Oggetti dell'API Graph di Workplace

I seguenti nodi sono accessibili tramite l'API Graph di Workplace utilizzando un'integrazione personalizzata o un token d'accesso di app di terzi.

Community

Una community di Workplace. Il gruppo principale per le chiamate all'API Graph di Workplace.

Gruppi

Un gruppo di Workplace.

Post

Un post creato in un gruppo o sul profilo di un membro.

Membri

Un account per uno specifico utente di Workplace. Questo nodo viene utilizzato anche per la visualizzazione e la modifica dei messaggi ricevuti e inviati da questo utente.

Competenze

Una competenza aggiunta al profilo di un membro.

Evento

Un evento del gruppo o della community di Workplace.

Categoria

Una categoria nell'Area risorse per memorizzare contenuti aziendali importanti.

Gruppo di persone

Una raccolta di persone definita utilizzando criteri o liste.

Contenuto segnalato

Contenuto su Workplace che è stato segnalato per il controllo da parte di un amministratore.

Turno

I dati del calendario turni per i dipendenti pagati a ore su Workplace.

Sondaggio

I sondaggi che sono stati creati su Workplace.

Esportazione dei dati

I processi di esportazione dei dati per l'esportazione di dati in gruppo da Workplace.

Per consultare gli esempi di combinazione di chiamate all'API Graph per risolvere problemi specifici, fai riferimento alla lista delle app di esempio.

Utilizzo dell'API Graph

Oggetti dell'API Graph

L'API Graph è una rappresentazione delle informazioni presenti su Workplace, composta da:

Nodi: oggetti, come un utente, una foto, un post o un commento
Segmenti: le connessioni tra questi elementi,come il file di un post o i commenti di una foto
Campi: i metadati relativi agli oggetti, come il nome di una persona o la privacy di un gruppo

Ogni elemento nel grafico di Workplace è rappresentato da un ID unico. I gruppi, i membri, i post e anche i commenti dispongono dei propri ID che possono essere utilizzati per recuperare le relative informazioni dall'API Graph.

Gestione della community

Ogni community di Workplace viene tenuta separata dalle altre community, quindi puoi utilizzare l'API Graph solo per l'accesso ai contenuti all'interno della tua community e in gruppi per più aziende in cui sono stati aggiunti membri della tua community.

Per finalità di accesso all'API Graph, la community viene gestita come un gruppo. Puoi pensare alla tua community come a un gruppo principale, al di sotto del quale tutti i gruppi vengono aggiunti come elementi secondari. Per recuperare informazioni sulla tua community sull'API Graph, avrai bisogno dell'ID della community, recuperato dall'API Graph in modo programmatico, effettuando una richiesta HTTP GET a graph.facebook.com/community con un token d'accesso dell'app valido.

Gestione delle versioni dell'API Graph

L'API Graph per Workplace è basata sull'API Graph per la piattaforma Facebook. Ciò implica che eredita lo stesso comportamento di gestione delle versioni dell'API utilizzato su Facebook.

Le versioni dell'API Graph vengono rilasciate approssimativamente ogni tre mesi e le modifiche a tutte le API di Workplace e Facebook vengono pubblicate nel registro modifiche dell'API Graph.

Quando si effettua una chiamata all'API Graph, puoi specificare una versione nel percorso all'API, nel modo seguente:

      https://graph.facebook.com/v2.11/community/groups

Tuttavia, sono presenti alcune restrizioni sulle versioni disponibili:

Quando viene rilasciata una nuova versione, diventa la versione dell'API corrente e la sua funzionalità è garantita per due anni dal momento del rilascio.
Quando viene creata un'app, l'impostazione predefinita è la versione dell'API corrente al momento della creazione e questa diventa la versione minima dell'API disponibile per quella specifica app.
Le app sono libere di specificare qualsiasi versione dell'API quando si effettuano chiamate all'API, ma non potranno effettuare chiamate alle versioni obsolete dell'API o alle versioni precedenti alla versione minima dell'API dell'app.
Per le chiamate all'API senza versione, l'impostazione predefinita è la versione minima dell'API per quella specifica app.

Quando viene creata una nuova integrazione personalizzata, la sua versione minima dell'API disponibile corrisponderà alla versione dell'API corrente al momento della creazione. Questa versione minima interessa sia le chiamate all'API Graph sia le iscrizioni ai webhook.

Gestione delle versioni della piattaforma Registro modifiche dell'API Graph

Controllo della versione dell'API Graph

In caso di dubbi sulla versione che stai utilizzando, puoi verificare questo aspetto in alcuni modi. Per controllare quale versione dell'API Graph può essere utilizzata con la tua app, puoi aggiungere il parametro debug alla chiamata all'API.

      https://graph.facebook.com/community?debug=all

In tal modo verranno restituite altre informazioni di debug a conferma della versione utilizzata.

      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "No API version was specified. This request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }

Se provi a utilizzare una versione precedente a quella minima dell'API minima per la tua app, il messaggio debug te lo indicherà.

      https://graph.facebook.com/v2.6/community?debug=all
      
      {
         "name": "Example Community",
         "privacy": "CLOSED",
         "id": "855210357923606",
         "__debug__": {
            "messages": [
               {
                  "link": "https://developers.facebook.com/docs/apps/versions/",
                  "message": "The app tried to call version v2.6. This app can only call versions v2.8 and higher, so the request defaulted to version v2.8.",
                  "type": "warning"
               }
            ]
         }
      }

Controllo delle versioni del webhook

Le iscrizioni al webhook utilizzano la versione minima dell'API se l'iscrizione è stata effettuata tramite la finestra di dialogo a comparsa Integrazione personalizzata oppure se la versione dell'API specificata corrisponde all'iscrizione che è stata effettuata tramite l'endpoint subscriptions dell'API Graph /app/subscriptions.

Puoi utilizzare l'endpoint subscriptions per confermare la versione del webhook applicata per ogni campo e argomento del webhook. Questo endpoint richiede un token d'accesso dell'app.

      https://graph.facebook.com/v2.11/app/subscriptions
      
      {
        "data": [
          {
            "object": "group",
            "callback_url": "https://www.example.com/callback",
            "active": true,
            "fields": [
              {
                "name": "comments",
                "version": "v2.8"
              },
      ...

A seconda della modalità di abilitazione dell'iscrizione al webhook, campi diversi all'interno di un singolo oggetto webhook possono restituire payload che utilizzando numeri di versione differenti.

Se il payload non è nel formato previsto, ricontrolla il numero di versione e attiva l'iscrizione di nuovo utilizzando una versione più recente, se necessario.

Utilizzo dei token d'accesso

Acquisizione di un token d'accesso dell'app

Per effettuare chiamate all'API Graph per la tua community, dovrai creare un'app e recuperare un token d'accesso. Ciò implica la creazione di una nuova integrazione personalizzata, in seguito la concessione delle autorizzazioni necessarie per la funzionalità che desideri creare.

Per maggiori informazioni sulla creazione di app e il modello di autorizzazione, consulta la guida sulle autorizzazioni.

Acquisizione di un token d'accesso del membro

Mentre un token d'accesso dell'app consente a un'app di accedere e interagire con oggetti a livello di community, un token d'accesso del membro consente a un servizio di effettuare chiamate per conto di un account specifico.

Puoi recuperare un token d'accesso del membro effettuando una richiesta GET all'endpoint /member_id per un determinato membro, utilizzando un token d'accesso dell'amministratore e richiedendo il campo aggiuntivo impersonate_token.

Questa funzionalità richiede l'autorizzazione Impersonate per consentire all'app di effettuare la chiamata.

Impersonate è un'autorizzazione obsoleta. Non creare nuove funzionalità utilizzando questa autorizzazione. Questa autorizzazione non può più essere aggiunta alle integrazioni personalizzate.

I token impersonate possono essere recuperati solo per gli account che sono stati reclamati.