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.

Le risposte sono allegate 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.

Utilizzare il parametro fields

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

Vincoli relativi ai commenti

Quando utilizzi commenti ancorati e non ancorati con l'API Drive, vengono applicati i seguenti vincoli:

Tipo di commento	Tipo di file
Ancorato	Gli sviluppatori possono definire il proprio formato per la specifica dell'ancora. L'ancoraggio viene salvato e restituito al momento del recupero del commento, tuttavia le app editor di Google Workspace trattano questi commenti come non ancorati.
Non ancorato	Supportati nei documenti Google Workspace, che li mostreranno nella visualizzazione "Tutti i commenti". I commenti non ancorati non vengono visualizzati nei PDF sottoposti a rendering nel visualizzatore di file di Drive, anche se vengono salvati e possono essere recuperati tramite l'API Drive.

Aggiungere un commento ancorato all'ultima revisione di un documento

Quando aggiungi un commento, potresti volerlo ancorare a una regione del file. Un ancora definisce una regione in un file a cui si riferisce un commento. La risorsa comments definisce il campo anchor come stringa JSON.

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 list sulla risorsa revisions per elencare ogni revisionID per un documento. Segui questo passaggio solo se vuoi ancorare un commento a una revisione diversa dall'ultima. Se vuoi utilizzare l'ultima revisione, usa head per revisionID.

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

Il seguente esempio di codice mostra come creare un commento ancorato:

Python

from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an anchored comment.'

# The line number to anchor the comment to.
# Note: Line numbers are based on the revision.
ANCHOR_LINE = 10
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_anchored_comment():
    """
    Create an anchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # Define the anchor region for the comment.
        # For Google Docs, the region is typically defined by 'line' and 'revision'.
        # Other file types might use different region classifiers.
        anchor = {
            'region': {
                'kind': 'drive#commentRegion',
                'line': ANCHOR_LINE,
                'rev': 'head'
            }
        }

        # The comment body.
        comment_body = {
            'content': COMMENT_TEXT,
            'anchor': anchor
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_anchored_comment()

L'API Drive restituisce un'istanza dell'oggetto risorsa comments che include la stringa anchor.

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.

Aggiungere un commento non ancorato

Per aggiungere un commento non ancorato, 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.

Il seguente esempio di codice mostra come creare un commento non ancorato:

Python

from google.oauth2.credentials import Credentials
from googleapiclient.errors import HttpError

# --- Configuration ---
# The ID of the file to comment on.
# Example: '1_aBcDeFgHiJkLmNoPqRsTuVwXyZ'
FILE_ID = 'FILE_ID'

# The text content of the comment.
COMMENT_TEXT = 'This is an example of an unanchored comment.'
# --- End of user-configuration section ---

SCOPES = ["https://www.googleapis.com/auth/drive"]

creds = Credentials.from_authorized_user_file("token.json", SCOPES)

def create_unanchored_comment():
    """
    Create an unanchored comment on a specific line in a Google Doc.

    Returns:
        The created comment object or None if an error occurred.
    """
    try:
        # Build the Drive API service
        service = build("drive", "v3", credentials=creds)

        # The comment body. For an unanchored comment,
        # omit the 'anchor' property.
        comment_body = {
            'content': COMMENT_TEXT
        }

        # Create the comment request.
        comment = (
            service.comments()
            .create(fileId=FILE_ID, fields="*", body=comment_body)
            .execute()
        )

        print(f"Comment ID: {comment.get('id')}")
        return comment

    except HttpError as error:
        print(f"An error occurred: {error}")
        return None

create_unanchored_comment()

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 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.

Richiesta

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 create sulla 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 comments 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)

Richiesta

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

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.

Richiesta

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: impostalo 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.

Richiesta

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 ulteriori informazioni, vedi Risolvere un commento.

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

Richiesta

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.

Richiesta

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

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

Argomenti correlati

• Panoramica di file e cartelle
• Gestire le revisioni dei file