mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-04-05 14:58:37 +07:00
150 lines
7.6 KiB
Plaintext
150 lines
7.6 KiB
Plaintext
---
|
||
title: '访问 API'
|
||
summary: '学习如何通过本文档的 "Try It" 功能与 Dify API 进行交互测试，获取关于 Base URL、API 密钥的重要信息，并了解如何为我们的文档生态做出贡献。'
|
||
---
|
||
|
||
欢迎来到 Dify API 文档中心！本指南旨在帮助您快速上手，了解如何有效地使用本文档提供的交互功能来测试和理解 Dify API，并掌握 API 访问的关键要素。
|
||
|
||
**重要提示：**
|
||
|
||
* **本页内容：** 主要介绍 API 文档的交互方式、全局访问配置（如 Base URL、API 密钥）以及文档贡献流程。
|
||
* **API 端点详情：** 所有具体的 API 端点（包括其参数、请求/响应结构、功能描述及示例）内容是根据我们的 OpenAPI 规范自动生成的，并包含了最新的功能注释。**请务必查阅这些自动生成的页面以获取最准确和详细的端点信息。**
|
||
|
||
<Card title="访问 API" icon="code" href="/api-reference/对话消息/发送对话消息" horizontal>
|
||
或点击顶部导航栏的`访问 API`标签页查看完整的 API 文档。
|
||
</Card>
|
||
|
||
---
|
||
|
||
## 交互式 API 测试
|
||
|
||
为了方便您快速验证和理解 API，本文档中大部分 API 端点页面都内嵌了 "Try It" 的交互式测试功能。
|
||
|
||
<Steps>
|
||
<Step title="定位 'Try It' 功能">
|
||
在您希望测试的 API 端点文档页面，通常在页面顶部或右侧区域，您会找到一个明显的 "Try It" 按钮或直接可交互的参数输入区域。
|
||
</Step>
|
||
<Step title="配置请求参数">
|
||
<AccordionGroup>
|
||
<Accordion title="服务器地址 (Base URL)">
|
||
系统可能会尝试预填，但请务必根据您的 Dify 部署环境（Cloud 或本地/私有化）选择或输入正确的 Base URL。详情请参阅下方的 [服务器地址 (Base URL)](#服务器地址-base-url) 部分。
|
||
</Accordion>
|
||
<Accordion title="认证信息 (API Key)">
|
||
在认证区域，您需要填入从 Dify 应用中获取的有效 API 密钥。详情请参阅 [API 密钥 (API Key)](#api-密钥-api-key) 部分。
|
||
</Accordion>
|
||
<Accordion title="路径与查询参数">
|
||
如果 API 端点的 URL 中包含路径参数 (如 `/users/{user_id}` )或需要查询参数 (如 `?limit=10` )，请根据端点说明准确填写。
|
||
</Accordion>
|
||
<Accordion title="请求体 (Request Body)">
|
||
对于 `POST`, `PUT`, `PATCH` 等需要请求体的 HTTP 方法，请参照端点文档中提供的请求体结构 (Schema) 和示例，构建正确的 JSON 内容。
|
||
</Accordion>
|
||
</AccordionGroup>
|
||
</Step>
|
||
<Step title="发送请求并查看结果">
|
||
所有参数配置完毕后，点击 "Send" (或 "Execute") 按钮发起 API 调用。稍后，您将在同一区域看到 API 返回的完整响应，包括 HTTP 状态码、响应头和响应体。
|
||
</Step>
|
||
</Steps>
|
||
|
||
---
|
||
|
||
## 🔑 API 访问配置
|
||
|
||
### 服务器地址 (Base URL)
|
||
|
||
API 请求的基础 URL 因您的 Dify 部署环境而异：
|
||
|
||
<CodeGroup>
|
||
```bash Dify Cloud (云服务版)
|
||
https://api.dify.ai/v1
|
||
```
|
||
|
||
```bash 本地/私有化部署
|
||
http://localhost/v1
|
||
```
|
||
</CodeGroup>
|
||
<Info>
|
||
在进行 API 调用或使用 "Try It" 功能时，请务必确认您配置的 Base URL 是正确的。
|
||
</Info>
|
||
|
||
### API 密钥 (API Key)
|
||
|
||
Dify 的**每个**应用 (App) 都拥有其专属的 API 密钥，用于接口调用的身份验证和授权。
|
||
|
||
* **获取途径：** 您可以在您的 Dify 应用的 概览 或 `访问 API` 或 `监控` 页面中点击 `API 密钥` 管理或生成您的 API 密钥。
|
||
|
||
* **使用方法：** 获取到 API 密钥后，请将其以 `Bearer YOUR_API_KEY` 的形式加入到 HTTP 请求的 `Authorization` 头部。
|
||
|
||
* **重要安全提示：**
|
||
<Warning>
|
||
API 密钥是访问您应用数据的凭证，具有较高权限。**请务必将其视为敏感信息并妥善保管，严禁在任何客户端（如浏览器、移动应用前端）代码中硬编码或直接暴露。** 推荐将 API 密钥存储在安全的服务器端环境，并通过后端服务代理对 Dify API 的调用。
|
||
</Warning>
|
||
|
||
* **访问控制：** 在 Dify 应用的 **监控 (Monitoring) -> 后端服务API (Backend Service API)** 设置中，您可以管理 API 的访问状态，例如暂时禁用所有 API 调用。
|
||
|
||
---
|
||
|
||
## 📚 关于`访问 API`以及本文档
|
||
|
||
### 文档的组成与来源
|
||
|
||
* **本指南页 (`api-access-readme.mdx`)：** 提供如何使用 API 文档、进行交互测试以及 API 访问的通用配置信息。
|
||
* **API 端点详情页：** 侧边栏 **"API 端点"** 分组下的所有页面，均由我们的 OpenAPI 规范 ([查看 OpenAPI 规范源文件模板](https://github.com/langgenius/dify/tree/main/web/app/components/develop/template)) **自动生成**。这些页面包含了每个端点的详细描述、参数、请求/响应示例和最新的功能注解。
|
||
|
||
### 如何为本文档做出贡献
|
||
|
||
我们非常欢迎并感谢社区成员对 Dify 文档的贡献！
|
||
|
||
<Tabs>
|
||
<Tab title="编辑当前页面 (本指南)">
|
||
如果您希望修改 **当前您正在阅读的这个 `API 访问与交互指南` 页面**，您可以：
|
||
1. 滚动到本页底部。
|
||
2. 点击 <Icon icon="pen-to-square" /> **"编辑此页" (Edit this page)** 按钮。
|
||
3. 这将会直接将您引导至 GitHub 上本 `api-access-readme.mdx` 文件的编辑界面。
|
||
|
||
<Note>
|
||
请注意：本页底部的 **"编辑此页"** 按钮 **仅作用于当前这个指南页面 (`api-access-readme.mdx`) 本身**。
|
||
它 **不适用于** `访问 API` 详情页面。
|
||
</Note>
|
||
</Tab>
|
||
|
||
<Tab title="修改 API 端点描述 (OpenAPI 规范)">
|
||
如果您发现 `访问 API` 详情页中某个具体 **API 端点的描述、参数说明或示例需要更新**，这些内容来源于 OpenAPI 规范文件。
|
||
1. 请前往 Dify 的文档代码仓库。
|
||
2. 定位到相关的 OpenAPI JSON 文件（按语言分子目录，如 `en/openapi_chatflow.json`, `zh-hans/openapi_workflow.json` 等）。
|
||
3. 修改对应的 OpenAPI 文件内容。
|
||
4. 提交 Pull Request 到 Dify 主仓库。
|
||
|
||
<Tip>
|
||
为了保持多语言文档的一致性，如果您修改了某个语言的 OpenAPI 文件，建议检查并同步更新其他语言版本中对应的 OpenAPI 文件。
|
||
</Tip>
|
||
</Tab>
|
||
|
||
<Tab title="报告问题或建议">
|
||
如果您发现了文档中的任何问题（无论是本指南页还是具体的 API 端点页），或者有改进建议：
|
||
1. 您可以使用页面底部（或侧边栏）的 **"报告问题" (Report an issue)** 链接。
|
||
2. 这通常会将您引导至本文档项目 (dify-docs) 在 GitHub 上的 Issues 页面。
|
||
3. 请详细描述您发现的问题、问题所在的页面链接以及您的改进建议。
|
||
|
||
<Check>
|
||
准确的问题报告和富有建设性的建议同样是对社区和项目的重要贡献！
|
||
</Check>
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
<Card title="同步" icon="rotate" href="https://github.com/langgenius/dify/tree/main/web/app/components/develop/template" horizontal>
|
||
API 文档同步自 Dify 主仓库。你可以点击这个卡片，在 GitHub 上查看原始的代码。如果你发现不同步或错误的地方，欢迎提交 PR 来贡献代码。
|
||
</Card>
|
||
|
||
所有贡献（无论是直接编辑还是报告问题）都需要一个 GitHub 账户。我们期待您的参与，共同打造更完善的 Dify 使用文档！
|
||
|
||
{/*
|
||
Contributing Section
|
||
DO NOT edit this section!
|
||
It will be automatically generated by the script.
|
||
*/}
|
||
|
||
---
|
||
|
||
[编辑此页面](https://github.com/langgenius/dify-docs/edit/main/zh-hans/openapi-api-access-readme.mdx) | [提交问题](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml)
|
||
|