Gestire commenti e risposte

I commenti sono feedback forniti dall'utente 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 testi, all'interno di una versione specifica di un documento. Al contrario, un commento non ancorato è semplicemente associato al documento.

Nota: nei file BLOB, l'API Google Drive supporta solo i commenti non ancorati. I commenti ancorati sui file blob o nei file degli 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 relative risposte è noto come discussione.

Aggiungere un commento non ancorato

Per aggiungere un commento non ancorato a un documento, chiama il metodo comments.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 abbia le autorizzazioni corrette per aggiungere commenti. Inoltre, solo l'autore di un commento o di una risposta può eliminarlo o modificarlo. 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, chiama il metodo replies.create con il commento, il parametro fileId e una risorsa replies contenente la risposta.

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

Aggiungi un commento ancorato all'ultima revisione di un documento

Quando aggiungi un commento, ti consigliamo di ancorarlo a una regione del file. Un ancora 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: nei file BLOB, l'API Drive supporta solo i commenti non ancorati. I commenti ancorati sui file blob o sugli editor di Documenti Google non sono supportati.

Importante: gli ancoraggi sono immutabili e la loro posizione rispetto ai contenuti 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 file immagine o 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 usare l'ultima revisione, usa head per revisionID.

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

La definizione di una regione dipende dal tipo di contenuti del documento con cui stai lavorando. Per saperne di più, 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ò eliminare o modificare un commento o una risposta. 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 commenti.

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 può essere un rettangolo bidimensionale per un'immagine, una riga di testo in un documento o un intervallo temporale in un video. Per definire una regione, seleziona l'classificatore della regione corrispondente al tipo di contenuti a cui stai tentando di eseguire l'ancoraggio. Ad esempio, se i tuoi contenuti sono testuali, probabilmente utilizzerai la categoria di classificazione delle regioni txt o line.

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

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

• La prima area inizia dalla 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ù applicabili alla posizione ancorata. Pertanto, devi indicare chiaramente nell'interfaccia utente a quale revisione appartiene ogni commento.

Risolvere un commento

Utilizza il metodo comment.update per impostare la proprietà resolved nella risorsa comments su true quando un commento è stato risolto.

Quando l'app imposta la proprietà resolved su true, l'interfaccia utente deve indicare che il commento è stato risolto. Ad esempio, la tua app potrebbe:

• Non consentire ulteriori risposte e attenuare tutte le risposte precedenti, oltre al commento originale.
• Nascondi i commenti risolti.

Eliminare un commento

Utilizza il metodo comments.delete per eliminare i commenti. Quando un commento viene eliminato, Drive contrassegna la risorsa del commento come "deleted": "true".

Elenco commenti

Utilizza il metodo comments.list per elencare i commenti. Se vuoi includere commenti eliminati nei risultati, imposta il campo includedDeleted su true.