google-docs（Google Docs 文档协作）

How to Use

Base URL: https://docs.googleapis.com/v1

Finding your Document ID: The document ID is in the URL: https://docs.google.com/document/d/{DOCUMENT_ID}/edit

1. Create New Document

Create a blank document with a title:

Write to /tmp/gdocs_request.json:

{
  "title": "My New Document"
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '{documentId, title, documentUrl: ("https://docs.google.com/document/d/" + .documentId + "/edit")}'

2. Get Document Content

Read the entire document structure and content:

curl -s "https://docs.googleapis.com/v1/documents/{document-id}" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" | jq '{title: .title, body: .body.content}'

3. Get Document Metadata Only

Get just the title and basic properties:

curl -s "https://docs.googleapis.com/v1/documents/{document-id}" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" | jq '{documentId, title, revisionId, suggestionsViewMode}'

4. Insert Text at Beginning

Insert text at the start of the document (index 1):

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "insertText": {
        "location": {
          "index": 1
        },
        "text": "Hello, this is my first paragraph.\n"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

5. Insert Text at Specific Location

Insert text at a specific index (get indexes from document content):

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "insertText": {
        "location": {
          "index": 25
        },
        "text": "This is inserted text.\n"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

6. Delete Content Range

Delete text from a specific range:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "deleteContentRange": {
        "range": {
          "startIndex": 1,
          "endIndex": 50
        }
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

7. Find and Replace Text

Replace all occurrences of text throughout the document:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "replaceAllText": {
        "containsText": {
          "text": "old text",
          "matchCase": true
        },
        "replaceText": "new text"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies[0].replaceAllText'

8. Format Text as Bold

Make text bold in a specific range:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "updateTextStyle": {
        "range": {
          "startIndex": 1,
          "endIndex": 20
        },
        "textStyle": {
          "bold": true
        },
        "fields": "bold"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

9. Format Text with Multiple Styles

Apply multiple text styles (bold, italic, font size, color):

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "updateTextStyle": {
        "range": {
          "startIndex": 1,
          "endIndex": 30
        },
        "textStyle": {
          "bold": true,
          "italic": true,
          "fontSize": {
            "magnitude": 14,
            "unit": "PT"
          },
          "foregroundColor": {
            "color": {
              "rgbColor": {
                "red": 0.2,
                "green": 0.4,
                "blue": 0.8
              }
            }
          }
        },
        "fields": "bold,italic,fontSize,foregroundColor"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

10. Set Paragraph Alignment

Change paragraph alignment (LEFT, CENTER, RIGHT, JUSTIFIED):

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "updateParagraphStyle": {
        "range": {
          "startIndex": 1,
          "endIndex": 50
        },
        "paragraphStyle": {
          "alignment": "CENTER"
        },
        "fields": "alignment"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

11. Create Bulleted List

Convert paragraphs to a bulleted list:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "createParagraphBullets": {
        "range": {
          "startIndex": 1,
          "endIndex": 100
        },
        "bulletPreset": "BULLET_DISC_CIRCLE_SQUARE"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

Available bullet presets:

• BULLET_DISC_CIRCLE_SQUARE
• BULLET_DIAMONDX_ARROW3D_SQUARE
• BULLET_CHECKBOX
• NUMBERED_DECIMAL_ALPHA_ROMAN
• NUMBERED_DECIMAL_NESTED

12. Insert Table

Insert a table with specified rows and columns:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "insertTable": {
        "rows": 3,
        "columns": 4,
        "location": {
          "index": 1
        }
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

13. Insert Page Break

Insert a page break at a specific location:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "insertPageBreak": {
        "location": {
          "index": 50
        }
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

14. Insert Inline Image

Insert an image from a URL:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "insertInlineImage": {
        "uri": "https://example.com/image.png",
        "location": {
          "index": 1
        },
        "objectSize": {
          "height": {
            "magnitude": 200,
            "unit": "PT"
          },
          "width": {
            "magnitude": 300,
            "unit": "PT"
          }
        }
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // .replies // "done"'

15. Batch Operations (Multiple Updates)

Combine multiple operations in a single request:

Write to /tmp/gdocs_request.json:

{
  "requests": [
    {
      "insertText": {
        "location": {
          "index": 1
        },
        "text": "Title: Important Document\n\n"
      }
    },
    {
      "updateTextStyle": {
        "range": {
          "startIndex": 1,
          "endIndex": 26
        },
        "textStyle": {
          "bold": true,
          "fontSize": {
            "magnitude": 18,
            "unit": "PT"
          }
        },
        "fields": "bold,fontSize"
      }
    },
    {
      "insertText": {
        "location": {
          "index": 28
        },
        "text": "This is the body text of the document.\n"
      }
    }
  ]
}

Then run:

curl -s -X POST "https://docs.googleapis.com/v1/documents/{document-id}:batchUpdate" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" --header "Content-Type: application/json" -d @/tmp/gdocs_request.json | jq '.error // (.replies | length)'

16. Extract Plain Text

Get just the text content from a document:

curl -s "https://docs.googleapis.com/v1/documents/{document-id}" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" | jq -r '.body.content[]?.paragraph?.elements[]?.textRun?.content' | tr -d '\0'

17. Get Document Structure

View document structure with element types and indexes:

curl -s "https://docs.googleapis.com/v1/documents/{document-id}" --header "Authorization: Bearer $GOOGLE_DOCS_TOKEN" | jq '.body.content[] | {startIndex, endIndex, paragraph: .paragraph.elements[0].textRun.content}'

Common Scopes

Use full URL: https://www.googleapis.com/auth/documents

Index Reference

Understanding indexes is critical for the Google Docs API:

• Index 1: Start of document body
• Index N: Each character, newline, and structural element increments the index
• End index: Use "endIndex": startIndex + textLength for ranges
• Tip: Get document content first to see current indexes

Text Style Fields

When using updateTextStyle, specify which fields to update in the fields parameter:

Use comma-separated for multiple: "fields": "bold,italic,fontSize"

Paragraph Style Fields

When using updateParagraphStyle:

Guidelines

1. Batch operations: Combine multiple requests in a single batchUpdate call to improve performance
2. Index calculation: Always get current document content to determine correct indexes
3. Request order: Requests are processed in order; later requests see effects of earlier ones
4. Fields parameter: Always specify which fields to update to avoid overwriting other properties
5. RGB colors: Color values range from 0.0 to 1.0 (not 0-255)
6. Share permissions: Ensure the authenticated user has edit access to the document
7. batchUpdate responses: Some operations (updateParagraphStyle, insertTable, insertPageBreak, insertInlineImage) return empty or absent .replies; output of "done" means success with no reply data. An .error key indicates failure.

API Reference

• REST Reference: https://developers.google.com/docs/api/reference/rest
• Guides: https://developers.google.com/docs/api/how-tos/overview
• OAuth Playground: https://developers.google.com/oauthplayground/
• Scopes: https://developers.google.com/identity/protocols/oauth2/scopes#docs
• Request Types: https://developers.google.com/docs/api/reference/rest/v1/documents/request