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 testi, 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. Collettivamente, un commento con risposte è noto come discussione.

Utilizzare il parametro fields

Per tutti i metodi (escluso delete) della comments risorsa, devi impostare il fields parametro di sistema per specificare i campi da restituire nella risposta. Nella maggior parte dei metodi delle risorse di 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 ulteriori informazioni, consulta Restituire campi specifici.

Vincoli dei commenti

Quando si utilizzano 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'ancoraggio. L'ancoraggio viene salvato e restituito quando si recupera il commento, ma le app di editor di Google Workspace trattano questi commenti come commenti non ancorati.
Non ancorato	Supportato nei documenti di Google Workspace, che li mostreranno nella visualizzazione "Tutti i commenti". I commenti non ancorati non vengono mostrati nei PDF sottoposti a rendering nel visualizzatore di anteprima dei 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 ancoraggio definisce una regione in un file a cui fa riferimento un commento. La risorsa comments definisce il campo anchor come stringa JSON.

Importante:gli ancoraggi sono immutabili e la loro posizione relativa 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 file di immagini o documenti di sola lettura.

Per aggiungere un commento ancorato:

1. (Facoltativo) Chiama il list metodo su la risorsa revisions per elencare ogni revisionID di 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 create metodo sulla comments risorsa con il fileID parametro, una comments risorsa contenente il commento e una stringa di ancoraggio JSON contenente il 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 il creatore di un commento o di una risposta può eliminare o modificare un commento o una risposta. Si verificano errori quando una persona con un ruolo diverso da quello di creatore tenta di eliminare o modificare un commento. Per evitare questi errori, controlla il author.me campo di la risorsa dei commenti.

Aggiungere un commento non ancorato

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

Il commento viene inserito come testo normale, ma il corpo della risposta fornisce un htmlContent campo 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 il creatore di un commento o di una risposta può eliminare o modificare un commento o una risposta. Si verificano errori quando un utente con un ruolo diverso da quello di creatore tenta di eliminare o modificare un commento. Per evitare questi errori, controlla il campo author.me di la 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 create metodo sulla replies risorsa con i fileId e commentId parametri. 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 del 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."
}

Risolvere un commento

Un commento può essere risolto solo pubblicando una risposta a un commento.

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

Il corpo della richiesta utilizza il action campo 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, l'interfaccia utente deve indicare che il commento è stato risolto. Ad esempio, la tua app potrebbe:

• Non consentire ulteriori risposte e oscurare tutte le risposte precedenti e il commento originale.
• Nascondere i commenti risolti.

Richiesta

In questo esempio, forniamo i parametri del 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."
}

Recuperare un commento

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

Il metodo restituisce un'istanza di una risorsa comments.

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

Richiesta

In questo esempio, forniamo i parametri del 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

Elencare i commenti

Per elencare i commenti su un file, utilizza il list metodo sulla risorsa comments con il fileId parametro. 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 dei risultati.

Richiesta

In questo esempio, forniamo il parametro del 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 update metodo 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 del campo comments è di sola lettura. Un commento può essere risolto solo pubblicando una risposta a un commento. Per ulteriori informazioni, consulta Risolvere un commento.

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

Richiesta

In questo esempio, forniamo i parametri del 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 delete metodo sulla comments risorsa con i fileId e commentId parametri.

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

Richiesta

In questo esempio, forniamo i parametri del 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