mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-03-27 13:28:32 +07:00
f1f025b75d
* move files & renames * rename files and doc entries * sync develop plugin files * update group label translations * some cleanups * update configs * update links * add remote debug doc * delete redundant slashes and unnecessary notes * update ja and zh links --------- Co-authored-by: Riskey <riskey47@dify.ai>
132 lines
5.2 KiB
Plaintext
132 lines
5.2 KiB
Plaintext
---
|
||
dimensions:
|
||
type:
|
||
primary: reference
|
||
detail: examples
|
||
level: intermediate
|
||
standard_title: Endpoint
|
||
language: en
|
||
title: Neko Cat Endpoint
|
||
description: Authors Yeuoly, Allen. This document details the structure and implementation
|
||
of Endpoints in Dify plugins, using the Neko Cat project as an example. It covers
|
||
defining Endpoint groups, configuring interfaces, implementing the _invoke method,
|
||
and handling requests and responses. The document explains the meaning and usage
|
||
of various YAML configuration fields.
|
||
---
|
||
|
||
<Note> ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考[英文原版](/en/develop-plugin/dev-guides-and-walkthroughs/endpoint)。</Note>
|
||
|
||
# Endpoint
|
||
|
||
本文档以 [Neko Cat](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint) 项目为例，介绍插件中 Endpoint 的结构。Endpoint 是插件暴露的 HTTP 接口，可用于与外部系统集成。完整的插件代码请参考 [GitHub 仓库](https://github.com/langgenius/dify-plugin-sdks/tree/main/python/examples/neko)。
|
||
|
||
### 分组定义
|
||
|
||
`Endpoint` 分组是多个 `Endpoint` 的集合。在 Dify 插件中创建新的 `Endpoint` 时，你可能需要填写以下配置。
|
||
|
||
|
||
|
||
除了 `Endpoint Name` 之外，你可以通过编写分组的配置信息来添加新的表单项。点击保存后，你可以看到它包含的多个接口，这些接口将使用相同的配置信息。
|
||
|
||
|
||
|
||
#### **结构**
|
||
|
||
* `settings` (map[string] [ProviderConfig](/zh/develop-plugin/features-and-specs/plugin-types/general-specifications#providerconfig))：Endpoint 配置定义。
|
||
* `endpoints` (list[string], 必填)：指向具体的 `endpoint` 接口定义。
|
||
|
||
```yaml
|
||
settings:
|
||
api_key:
|
||
type: secret-input
|
||
required: true
|
||
label:
|
||
en_US: API key
|
||
zh_Hans: API key
|
||
ja_Jp: API key
|
||
pt_BR: API key
|
||
placeholder:
|
||
en_US: Please input your API key
|
||
zh_Hans: 请输入你的 API key
|
||
ja_Jp: あなたの API key を入れてください
|
||
pt_BR: Por favor, insira sua chave API
|
||
endpoints:
|
||
- endpoints/duck.yaml
|
||
- endpoints/neko.yaml
|
||
```
|
||
|
||
### 接口定义
|
||
|
||
* `path` (string)：遵循 Werkzeug 接口标准。
|
||
* `method` (string)：接口方法，仅支持 `HEAD`、`GET`、`POST`、`PUT`、`DELETE`、`OPTIONS`。
|
||
* `extra` (object)：基本详情之外的配置信息。
|
||
* `python` (object)
|
||
* `source` (string)：实现此接口的源代码。
|
||
|
||
```yaml
|
||
path: "/duck/<app_id>"
|
||
method: "GET"
|
||
extra:
|
||
python:
|
||
source: "endpoints/duck.py"
|
||
```
|
||
|
||
### 接口实现
|
||
|
||
你需要实现一个继承自 `dify_plugin.Endpoint` 的子类，并实现 `_invoke` 方法。
|
||
|
||
* **输入参数**
|
||
* `r` (Request)：来自 `werkzeug` 的 `Request` 对象。
|
||
* `values` (Mapping)：从路径解析的路径参数。
|
||
* `settings` (Mapping)：此 `Endpoint` 的配置信息。
|
||
* **返回**
|
||
* 来自 `werkzeug` 的 `Response` 对象，支持流式响应。
|
||
* 不支持直接返回字符串。
|
||
|
||
示例代码：
|
||
|
||
```python
|
||
import json
|
||
from typing import Mapping
|
||
from werkzeug import Request, Response
|
||
from dify_plugin import Endpoint
|
||
|
||
class Duck(Endpoint):
|
||
def _invoke(self, r: Request, values: Mapping, settings: Mapping) -> Response:
|
||
"""
|
||
Invokes the endpoint with the given request.
|
||
"""
|
||
app_id = values["app_id"]
|
||
|
||
def generator():
|
||
yield f"{app_id} <br>"
|
||
|
||
return Response(generator(), status=200, content_type="text/html")
|
||
```
|
||
|
||
## 注意事项
|
||
|
||
* Endpoint 仅在插件被调用时实例化；它们不是长期运行的服务。
|
||
* 开发 Endpoint 时请注意安全性，避免执行危险操作。
|
||
* Endpoint 可用于处理 Webhook 回调或为其他系统提供连接接口。
|
||
|
||
如果你正在学习插件开发，建议先阅读[插件开发入门](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin)和[开发者速查表](/zh/develop-plugin/dev-guides-and-walkthroughs/cheatsheet)。
|
||
|
||
## 相关资源
|
||
|
||
* [插件开发基本概念](/zh/develop-plugin/getting-started/getting-started-dify-plugin) - 了解插件开发的整体架构。
|
||
* [Neko Cat 示例](/zh/develop-plugin/dev-guides-and-walkthroughs/endpoint) - 扩展插件开发示例。
|
||
* [通用规范定义](/zh/develop-plugin/features-and-specs/plugin-types/general-specifications) - 了解 ProviderConfig 等通用结构。
|
||
* [开发 Slack Bot 插件示例](/zh/develop-plugin/dev-guides-and-walkthroughs/develop-a-slack-bot-plugin) - 另一个插件开发示例。
|
||
* [插件开发入门](/zh/develop-plugin/dev-guides-and-walkthroughs/tool-plugin) - 从零开始开发插件。
|
||
* [反向调用 Dify 服务](/zh/develop-plugin/features-and-specs/advanced-development/reverse-invocation-app) - 了解如何使用反向调用功能。
|
||
|
||
{/*
|
||
Contributing Section
|
||
DO NOT edit this section!
|
||
It will be automatically generated by the script.
|
||
*/}
|
||
|
||
---
|
||
|
||
[Edit this page](https://github.com/langgenius/dify-docs/edit/main/en/develop-plugin/dev-guides-and-walkthroughs/endpoint.mdx) | [Report an issue](https://github.com/langgenius/dify-docs/issues/new?template=docs.yml) |