Gestire commenti e risposte

I commenti sono feedback forniti dagli utenti su un file, ad esempio un lettore di un documento di elaborazione testi che suggerisce come riformulare una frase. Esistono due tipi di commenti: commenti ancorati e commenti non ancorati. Un commento ancorato è associato a una posizione specifica, ad esempio una frase in un documento di elaborazione del testo, all'interno di una versione specifica di un documento. Al contrario, un commento non ancorato è associato solo al documento.

Nota :sui file blob, l'API Google Drive supporta solo i commenti non ancorati. I commenti ancorati ai file blob o ai file dell'editor di Documenti Google non sono supportati.

Le risposte sono associate ai commenti e rappresentano la risposta di un utente al commento. L'API Drive consente agli utenti di aggiungere commenti e risposte ai documenti creati dalla tua app. Un commento con le risposte è noto collettivamente come discussione.

Per tutti i metodi (escluso delete) nella risorsa comments, devi impostare il parametro fields system per specificare i campi da restituire nella risposta. Nella maggior parte dei metodi Drive, questa azione è necessaria solo per restituire campi non predefiniti, ma è obbligatoria per la risorsa comments. Se ometti il parametro, il metodo restituisce un errore. Per saperne di più, consulta Restituire campi specifici.

Aggiungere un commento non ancorato

Per aggiungere un commento non ancorato a un documento, chiama il metodo create con il parametro fileId e una risorsa comments contenente il commento.

Il commento viene inserito come testo normale, ma il corpo della risposta fornisce un campo htmlContent contenente contenuti formattati per la visualizzazione.

Importante: ti consigliamo di verificare che un utente disponga delle autorizzazioni corrette per aggiungere commenti. Inoltre, solo l'autore di un commento o di una risposta può eliminarli o modificarli. Si verificano errori quando un utente con un ruolo diverso da quello di creator tenta di eliminare o modificare un commento. Per evitare questi errori, controlla il campo author.me della risorsa comments per assicurarti che l'utente che effettua la richiesta sia l'autore del commento e poi verifica le sue autorizzazioni relative al commento.

Aggiungere una risposta a un commento

Per aggiungere una risposta a un commento, utilizza il metodo replies.create nella risorsa replies con i parametri fileId e commentId. Il corpo della richiesta utilizza il campo content per aggiungere la risposta.

La risposta viene inserita come testo normale, ma il corpo della risposta fornisce un campo htmlContent contenente contenuti formattati per la visualizzazione.

Il metodo restituisce i campi elencati nel campo fields.

Richiedi

In questo esempio, forniamo i parametri di percorso fileId e commentId e più campi.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

Corpo della richiesta

{
  "content": "This is a reply to a comment."
}

Risolvi un commento

Un commento può essere risolto solo pubblicando una risposta.

Per risolvere un commento, utilizza il metodo replies.create nella risorsa replies con i parametri fileId e commentId.

Il corpo della richiesta utilizza il campo action per risolvere il commento. Puoi anche impostare il campo content per aggiungere una risposta che chiude il commento.

Quando un commento viene risolto, Drive contrassegna la risorsa commento come resolved: true. A differenza dei commenti eliminati, i commenti risolti possono includere i campi htmlContent o content.

Quando la tua app risolve un commento, la tua UI deve indicare che il commento è stato risolto. Ad esempio, la tua app potrebbe:

• Impedisci ulteriori risposte e attenua tutte le risposte precedenti e il commento originale.
• Nascondi commenti risolti. (facoltativo)

Richiedi

In questo esempio, forniamo i parametri di percorso fileId e commentId e più campi.

POST https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID/replies?fields=id,comment

Corpo della richiesta

{
  "action": "resolve",
  "content": "This comment has been resolved."
}

Aggiungere un commento ancorato all'ultima revisione di un documento

Quando aggiungi un commento, potresti volerlo ancorare a una regione del file. Un ancoraggio definisce la revisione e la regione di un file a cui fa riferimento un commento. La risorsa comments definisce il campo anchor come stringa JSON.

Nota :sui file blob, l'API Drive supporta solo i commenti non ancorati. I commenti ancorati ai file blob o ai file dell'editor di Documenti Google non sono supportati.

Importante: le ancore sono immutabili e la loro posizione rispetto al contenuto di un documento non può essere garantita tra le revisioni. Ti consigliamo di utilizzare gli ancoraggi nei documenti in cui la posizione non cambia, ad esempio nei file immagine o nei documenti di sola lettura.

Per aggiungere un commento ancorato:

1. (Facoltativo) Chiama il metodo revisions.list per elencare ogni revisionID per un documento. Segui questo passaggio solo se vuoi ancorare un commento a una revisione diversa da quella più recente. Se vuoi utilizzare l'ultima revisione, usa head per revisionID.

2. Chiama il metodo create con il parametro fileID, una risorsa comments contenente il commento e una stringa di ancoraggio JSON contenente revisionID (r) e regione (a).

Il modo in cui definisci una regione dipende dal tipo di contenuti del documento con cui stai lavorando. Per ulteriori informazioni, consulta Definire una regione.

Nota: ti consigliamo di verificare che un utente disponga delle autorizzazioni corrette per aggiungere commenti. Inoltre, solo l'autore di un commento o di una risposta può eliminarli o modificarli. Gli errori si verificano quando una persona con un ruolo diverso da quello di creator tenta di eliminare o modificare un commento. Per evitare questi errori, controlla il campo author.me della risorsa comments.

Definisci una regione

Come accennato in precedenza, la stringa di ancoraggio JSON contiene un revisionID (r) e una regione (a). La regione (a) è un array JSON contenente classificatori di regione che specificano il formato e la posizione a cui è ancorato un commento. Un classificatore potrebbe essere un rettangolo bidimensionale per un'immagine, una riga di testo in un documento o una durata di tempo in un video. Per definire una regione, seleziona il classificatore di regione che corrisponde al tipo di contenuti a cui stai cercando di ancorare. Ad esempio, se i tuoi contenuti sono di testo, probabilmente utilizzerai il classificatore di regioni txt o line.

Per un elenco dei classificatori di regioni nell'API Drive, consulta Classificatori di regioni.

L'esempio seguente mostra una stringa di ancoraggio JSON che ancora i commenti alle righe in due aree separate di un documento:

• La prima area inizia alla riga 12 ('n':12) e si estende per tre righe ('l':3).
• La seconda area copre solo la riga 18 ('n':18, 'l':1`).

    {
      'r': 'REVISION_ID',
      'a': [
      {
        'line':
        {
          'n': 12,
          'l': 3,
        }
      },
      {
        'line':
        {
          'n': 18,
          'l': 1,
        }
      }]
    }

Sostituisci REVISION_ID con head o con l'ID di una revisione specifica.

Importante: se la tua app consente agli utenti di aggiornare e condividere più revisioni di un documento, i commenti sulle revisioni precedenti potrebbero non essere più pertinenti alla posizione ancorata. Pertanto, devi indicare chiaramente nell'interfaccia utente a quale revisione appartiene ogni commento.

Ricevere un commento

Per ottenere un commento su un file, utilizza il metodo get nella risorsa comments con i parametri fileId e commentId. Se non conosci l'ID commento, puoi elencare tutti i commenti utilizzando il metodo list.

Il metodo restituisce un'istanza di una risorsa comments.

Per includere i commenti eliminati nei risultati, imposta il parametro di query includedDeleted su true.

Richiedi

In questo esempio, forniamo i parametri di percorso fileId e commentId e più campi.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment,modifiedTime,resolved

Elenco commenti

Per elencare i commenti su un file, utilizza il metodo list nella risorsa comments con il parametro fileId. Il metodo restituisce un elenco di commenti.

Trasmetti i seguenti parametri di query per personalizzare la paginazione o filtrare i commenti:

• includeDeleted: imposta su true per includere i commenti eliminati. I commenti eliminati non includono i campi htmlContent o content.

• pageSize: il numero massimo di commenti da restituire per pagina.

• pageToken: un token di pagina ricevuto da una precedente chiamata dell'elenco. Fornisci questo token per recuperare la pagina successiva.

• startModifiedTime: Il valore minimo del campo modifiedTime per i commenti sui risultati.

Richiedi

In questo esempio, forniamo il parametro di percorso fileId, il parametro di query includeDeleted e più campi.

GET https://www.googleapis.com/drive/v3/files/FILE_ID/comments?includeDeleted=true&fields=(id,comment,kind,modifiedTime,resolved)

Aggiornare un commento

Per aggiornare un commento su un file, utilizza il metodo update sulla risorsa comments con i parametri fileId e commentId. Il corpo della richiesta utilizza il campo content per aggiornare il commento.

Il campo booleano resolved nella risorsa comments è di sola lettura. Un commento può essere risolto solo pubblicando una risposta. Per saperne di più, consulta la sezione Risolvere un commento.

Il metodo restituisce i campi elencati nel parametro di query fields.

Richiedi

In questo esempio, forniamo i parametri di percorso fileId e commentId e più campi.

PATCH https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID?fields=id,comment

Corpo della richiesta

{
  "content": "This comment is now updated."
}

Eliminare un commento

Per eliminare un commento su un file, utilizza il metodo delete sulla risorsa comments con i parametri fileId e commentId.

Quando un commento viene eliminato, Drive contrassegna la risorsa commento come deleted: true. I commenti eliminati non includono i campi htmlContent o content.

Richiedi

In questo esempio, forniamo i parametri di percorso fileId e commentId.

DELETE https://www.googleapis.com/drive/v3/files/FILE_ID/comments/COMMENT_ID