GPT Actions 库：Google Drive 集成指南
技术背景
GPT Actions 允许开发者将外部 API 集成到自定义 GPT 中，扩展其能力。Google Drive 作为广泛使用的云存储服务，集成后可让 ChatGPT 直接访问用户文件，实现自然语言驱动的文件查询、内容摘要和数据分析。此集成适用于处理小型文档（如会议记录、产品设计文档），对于大型文件（如整本书）建议使用专门的 Google Docs 或 Sheets 集成。主要限制包括 API 调用频率、文件大小和 OAuth 权限管理。
核心原理
核心原理是通过 OpenAPI 规范定义 GPT 可调用的函数（如 listFiles、getMetadata、export），并利用 OAuth 2.0 进行用户授权。GPT 根据用户指令和上下文，自动选择合适的函数调用，将返回的数据作为上下文生成回答。数据流为：用户输入 -> GPT 解析 -> 调用 API -> 获取数据 -> 模型处理 -> 输出。关键设计决策包括使用 export 而非 get 来避免二进制下载问题，以及通过查询参数（q）灵活过滤文件。
架构分析
系统架构分为三层：客户端（ChatGPT）、GPT Actions 层（OpenAPI 定义）和 Google Drive API。GPT Actions 层作为中间件，将自然语言请求映射为 REST API 调用。OpenAPI 规范定义了服务器 URL、路径、参数和响应结构，确保 GPT 能正确解析。身份验证采用 OAuth 2.0，通过授权码流程获取访问令牌。设计上，通过提供多个操作（list、metadata、export）实现功能分层，并利用查询参数实现灵活搜索。
完整实战教程
简介
本页面为开发者构建特定应用的 GPT Action 提供说明和指南。在继续之前，请确保您已熟悉以下信息：
此特定 GPT Action 概述了如何连接到 Google Drive（Google 的文件存储系统）。此操作将允许您列出和查询文件名，将文件内容加载到您的 GPT 中，并最终在 ChatGPT 中使用该数据作为上下文。这组操作可通过 Google Drive API 中提供的其他方法进行扩展。如果您想要一个能够读取较小文件的通用 GPT，这将非常有用，例如：
* 会议记录
* 产品设计文档
* 简短备忘录
* 常见问题解答
对于需要读取较长备忘录（如整本书、包含多行的复杂 CSV）的情况，我们建议构建一个专门针对 Google Docs 或 Google Sheets 的 GPT。
价值 + 示例业务案例
用户现在可以利用 ChatGPT 的自然语言能力直接连接到 Google Drive 中的文件。
示例用例：
- 用户需要查找与某个主题相关的文件
- 用户需要回答一个关键问题，而该问题深藏在文档中
应用信息
应用关键链接
在开始之前，请查看应用中的这些链接：
* 应用网站：https://www.google.com/drive/
* 应用 API 文档：https://developers.google.com/drive/api/guides/about-sdk
应用前置条件
在开始之前，请确保您拥有 Google Cloud 账户，并且已启用 Drive API：
* 设置 Google Cloud 项目
* 从 Google API 库启用 Google Drive API
* 如果应用的“发布状态”为“测试”，请确保用户已添加到您的应用中
ChatGPT 步骤
示例自定义 GPT 指令
创建自定义 GPT 后，要开始使用，请将以下文本复制到“说明”面板中。您可能需要根据您的具体用例添加额外的上下文。这样，值得测试您添加的其他指令，以优化清晰度和准确性。有问题吗？请查看入门示例，了解此步骤的更多详细信息。
*** Context ***
You are an office helper who takes a look at files within Google Drive and reads in information. In this way, when asked about something, please take a look at all of the relevant information within the drive. Respect file names, but also take a look at each document and sheet.
*** Instructions ***
Use the 'listFiles' function to get a list of files available within docs. In this way, determine out of this list which files make the most sense for you to pull back taking into account name and title. After the output of listFiles is called into context, act like a normal business analyst. Things you could be asked to be are:
- Summaries: what happens in a given file? Please give a consistent, concise answer and read through the entire file before giving an answer.
- Professionalism: Behave professionally, providing clear and concise responses.
- Synthesis, Coding, and Data Analysis: ensure coding blocks are explained.
- When handling dates: make sure that dates are searched using date fields and also if you don't find anything, use titles.
- Clarification: Ask for clarification when needed to ensure accuracy and completeness in fulfilling user requests. Try to make sure you know exactly what is being asked.
- Privacy and Security: Respect user privacy and handle all data securely.
*** Examples of Documentation ***
Here is the relevant query documentation from Google for the listFiles function:
What you want to query Example
Files with the name "hello" name = 'hello'
Files with a name containing the words "hello" and "goodbye" name contains 'hello' and name contains 'goodbye'
Files with a name that does not contain the word "hello" not name contains 'hello'
Folders that are Google apps or have the folder MIME type mimeType = 'application/vnd.google-apps.folder'
Files that are not folders mimeType != 'application/vnd.google-apps.folder'
Files that contain the text "important" and in the trash fullText contains 'important' and trashed = true
Files that contain the word "hello" fullText contains 'hello'
Files that do not have the word "hello" not fullText contains 'hello'
Files that contain the exact phrase "hello world" fullText contains '"hello world"'
Files with a query that contains the "\" character (e.g., "\authors") fullText contains '\\authors'
Files with ID within a collection, e.g. parents collection '1234567' in parents
Files in an application data folder in a collection 'appDataFolder' in parents
Files for which user "test@example.org" has write permission 'test@example.org' in writers
Files for which members of the group "group@example.org" have write permission 'group@example.org' in writers
Files modified after a given date modifiedTime > '2012-06-04T12:00:00' // default time zone is UTC
Files shared with the authorized user with "hello" in the name sharedWithMe and name contains 'hello'
Files that have not been shared with anyone or domains (only private, or shared with specific users or groups) visibility = 'limited'
Image or video files modified after a specific date modifiedTime > '2012-06-04T12:00:00' and (mimeType contains 'image/' or mimeType contains 'video/')
OpenAPI 架构示例
创建自定义 GPT 后，将以下文本复制到 Actions 面板中。这提供了你可以作为 GPT 函数包含的内容示例。
有问题吗？查看 入门示例 以了解此步骤的更多详细信息。此外，可以尝试 ActionsGPT，这是 OpenAI 创建的用于帮助处理 Actions 的自定义 GPT。三个示例是：
* 列出文件：这是列出你云端硬盘中文件的核心操作。其中包含一些参数，例如 q、includeItemsFromAllDrives、supportsAllDrives。
* 获取元数据：如果列表操作不起作用，这可以作为基于某些结果的备份——例如，如果用户尝试通过“上周的会议”等进行搜索。
* 导出：以字节内容导出。更多阅读，请参阅 https://developers.google.com/drive/api/reference/rest/v3/files/export。
通常，如果使用“获取”，模型将尝试下载文件，这可能不是期望的行为。因此，建议使用导出。
{
"openapi": "3.1.0",
"info": {
"title": "Google Drive API",
"description": "API for interacting with Google Drive",
"version": "1.0.0"
},
"servers": [
{
"url": "https://www.googleapis.com/drive/v3"
}
],
"paths": {
"/files": {
"get": {
"operationId": "ListFiles",
"summary": "List files",
"description": "Retrieve a list of files in the user's Google Drive.",
"parameters": [
{
"name": "q",
"in": "query",
"description": "Query string for searching files.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "includeItemsFromAllDrives",
"in": "query",
"description": "Whether both My Drive and shared drive items should be included in results.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "supportsAllDrives",
"in": "query",
"description": "Whether the requesting application supports both My Drives and shared drives.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "pageSize",
"in": "query",
"description": "Maximum number of files to return.",
"required": false,
"schema": {
"type": "integer",
"default": 10
}
},
{
"name": "pageToken",
"in": "query",
"description": "Token for continuing a previous list request.",
"required": false,
"schema": {
"type": "string"
}
},
{
"name": "fields",
"in": "query",
"description": "Comma-separated list of fields to include in the response.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "A list of files.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"example": "drive#fileList"
},
"nextPageToken": {
"type": "string",
"description": "Token to retrieve the next page of results."
},
"files": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"mimeType": {
"type": "string"
}
}
}
}
}
}
}
}
}
}
}
},
"/files/{fileId}": {
"get": {
"operationId": "getMetadata",
"summary": "Get file metadata",
"description": "Retrieve metadata for a specific file.",
"parameters": [
{
"name": "fileId",
"in": "path",
"description": "ID of the file to retrieve.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "fields",
"in": "query",
"description": "Comma-separated list of fields to include in the response.",
"required": false,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "Metadata of the file.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"mimeType": {
"type": "string"
},
"description": {
"type": "string"
},
"createdTime": {
"type": "string",
"format": "date-time"
}
}
}
}
}
}
}
}
},
"/files/{fileId}/export": {
"get": {
"operationId": "export",
"summary": "Export a file",
"description": "Export a Google Doc to the requested MIME type.",
"parameters": [
{
"name": "fileId",
"in": "path",
"description": "ID of the file to export.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "mimeType",
"in": "query",
"description": "The MIME type of the format to export to.",
"required": true,
"schema": {
"type": "string",
"enum": [
"application/pdf",
"application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"text/plain"
]
}
}
],
"responses": {
"200": {
"description": "The exported file.",
"content": {
"application/pdf": {
"schema": {
"type": "string",
"format": "binary"
}
},
"application/vnd.openxmlformats-officedocument.wordprocessingml.document": {
"schema": {
"type": "string",
"format": "binary"
}
},
"text/plain": {
"schema": {
"type": "string",
"format": "binary"
}
}
}
},
"400": {
"description": "Invalid MIME type or file ID."
},
"404": {
"description": "File not found."
}
}
}
}
}
}
身份验证说明
以下是有关如何与此第三方应用设置身份验证的说明。有疑问？请查看入门示例，了解此步骤的更多详细信息。
操作前步骤
在 ChatGPT 中设置身份验证之前，请先在应用中执行以下步骤。
* 转到 Google Cloud Console
* 导航到“已启用的 API 和服务”，并启用 Google Drive API
* 在搜索栏中，搜索 Google Drive API：
* 创建新的 OAuth 凭据（或使用现有的凭据）。请注意，如果你尚未设置 OAuth 凭据屏幕，则需要先进行设置。
* 在此过程中，您需要授予正确的权限，如果启用了测试，则将主要测试者设置为测试电子邮件，并设置 OAuth 速率限制。
* 接下来，转到凭据并点击“+ 创建凭据”，然后点击“创建凭据”。以下是此屏幕已设置好的示例。
* 找到你的 OAuth 客户端 ID 和客户端密钥，并安全地存储这两个值（见下方截图）
### 在 ChatGPT 中
在 ChatGPT 中，点击“Authentication”（身份验证）并选择 “OAuth”。输入以下信息。
* Client ID：使用上面步骤中的 Client ID
* Client Secret：使用上面步骤中的 Client Secret
* Authorization URL：https://accounts.google.com/o/oauth2/auth
* Token URL：https://oauth2.googleapis.com/token
* Scope：https://www.googleapis.com/auth/drive
* 注意：有关更多详细作用域的列表，请参阅 Google 的 OAuth 2.0 指南。
* Token：默认（POST）
* Privacy Policy：https://policies.google.com/privacy?hl=en-US
操作后步骤
在 ChatGPT 中设置好身份验证后，请按照以下步骤在应用程序中完成操作。
* 从 GPT 操作中复制回调 URL
* 在“Authorized redirect URIs”中，添加你的回调 URL
### 常见问题与故障排除
* _回调 URL 错误：_ 如果在 ChatGPT 中遇到回调 URL 错误，请仔细查看上面的截图。你需要将回调 URL 直接添加到 GCP 中，以便操作能够正确进行身份验证。
_你希望我们优先处理哪些集成？我们的集成是否存在错误？请在 GitHub 中提交 PR 或 issue，我们会及时查看。_
<!-- watermark --><div style="background-color:#FFFFFF"><p style="color:#FFFFFF; font-size: 1px">gd2md-html: xyzzy Mon Aug 12 2024</p></div>
常见问题
常见错误包括：1) 回调 URL 未正确配置，导致 OAuth 失败，需在 GCP 中添加 GPT 提供的回调 URL；2) 权限不足，需确保 OAuth 范围包含 drive.readonly 或 drive；3) 文件导出失败，检查 MIME 类型是否支持；4) 查询语法错误，参考 Google Drive API 文档。排查方法：检查 API 响应状态码，使用 Postman 测试 API，查看 GPT 日志。生产环境优化：使用分页（pageSize）限制返回数量，缓存常用文件元数据，设置合理的超时和重试机制。
企业应用扩展
可扩展性：1) 增加更多 Drive API 操作，如上传文件、创建文件夹、搜索文件内容；2) 集成 Google Docs 和 Sheets API，处理复杂文档；3) 添加多文件批量处理功能；4) 实现文件变更监听，实时更新上下文；5) 结合向量数据库，实现语义搜索。优化建议：使用异步处理大文件，引入缓存层减少 API 调用，设计更精细的权限控制。
总结
本教程面向有编程基础的开发者，详细讲解如何构建一个连接 Google Drive 的 GPT Action。通过配置自定义 GPT 指令和 OpenAPI 架构，实现文件列表、元数据获取和内容导出，使 ChatGPT 能读取并分析 Drive 中的文档。教程涵盖技术背景、核心原理、架构设计、身份验证配置、常见错误排查及生产环境优化，帮助开发者快速落地 AI 工程实践。
- --
内容来源与验证
- 内容等级：PREMIUM_A
- 质量等级：A
- 难度：中级
- 验证等级：V1
- 原文作者：lxing-oai
- 原文日期：2024-08-11
- 来源许可：MIT
- 来源版本：
a70f062d011ca7582abbf649d91e95e4c9feb563 - 查看原文
站内还有更多完整实战教程
加入会员，解锁全部教程、完整代码与持续更新内容。
加入会员