Evennia REST API¶

Evennia 通过 REST API 使其数据库可访问，如果使用默认设置在本地运行，可以在 http://localhost:4001/api 找到。该 API 允许你从游戏外部检索、编辑和创建资源，例如使用你自己的自定义客户端或游戏编辑器。虽然你可以在网页浏览器中查看和了解 API，但它实际上是为其他程序在代码中访问而设计的。

该 API 使用 Django Rest Framework。这自动化了设置视图（Python 代码）以处理网页请求结果的过程。检索数据的过程与 Webserver 页面上解释的类似，只不过这里的视图将返回你想要的资源的 JSON 数据。你也可以发送这样的 JSON 数据以从外部更新数据库。

使用方法¶

要激活 API，请在你的设置文件中添加以下内容：

REST_API_ENABLED = True

主要的控制设置是 REST_FRAMEWORK，这是一个字典。键 DEFAULT_LIST_PERMISSION 和 DEFAULT_CREATE_PERMISSIONS 分别控制谁可以通过 API 查看和创建新对象。默认情况下，具有 ‘Builder’-level permission 或更高权限的用户可以访问这两种操作。

虽然 API 是为了扩展而设计的，但 Evennia 提供了一些开箱即用的操作。如果你点击 /api 网站右上角的 Autodoc 按钮，你会看到一个可用端点的精美图形展示。

以下是在 Python 中使用标准 requests 库调用 API 的示例：

>>> import requests
>>> response = requests.get("https://www.mygame.com/api", auth=("MyUsername", "password123"))
>>> response.json()
{'accounts': 'http://www.mygame.com/api/accounts/',
 'objects': 'http://www.mygame.com/api/objects/',
 'characters': 'http://www.mygame.com/api/characters/',
 'exits': 'http://www.mygame.com/api/exits/',
 'rooms': 'http://www.mygame.com/api/rooms/',
 'scripts': 'http://www.mygame.com/api/scripts/',
 'helpentries': 'http://www.mygame.com/api/helpentries/'}

要列出特定类型的对象：

>>> response = requests.get("https://www.mygame.com/api/objects",
                            auth=("Myusername", "password123"))
>>> response.json()
{
"count": 125,
"next": "https://www.mygame.com/api/objects/?limit=25&offset=25",
"previous": null,
"results" : [{"db_key": "A rusty longsword", "id": 57, "db_location": 213, ...}]}

在上面的示例中，现在在 “results” 数组中显示对象，同时它有一个 “count” 值表示总对象数，以及 “next” 和 “previous” 链接用于下一页和上一页（如果有）。这称为分页，链接显示 “limit” 和 “offset” 作为查询参数，可以添加到 URL 中以控制输出。

其他查询参数可以定义为过滤器，允许你进一步缩小结果范围。例如，仅获取具有开发者权限的账户：

>>> response = requests.get("https://www.mygame.com/api/accounts/?permission=developer",
                            auth=("MyUserName", "password123"))
>>> response.json()
{
"count": 1,
"results": [{"username": "bob",...}]
}

现在假设你想使用 API 创建一个 Object：

>>> data = {"db_key": "A shiny sword"}
>>> response = requests.post("https://www.mygame.com/api/objects",
                             data=data, auth=("Anotherusername", "mypassword"))
>>> response.json()
{"db_key": "A shiny sword", "id": 214, "db_location": None, ...}

在这里，我们向 /api/objects 端点发出了一个 HTTP POST 请求，带有我们想要的 db_key。我们收到了新创建对象的信息。你现在可以使用 PUT（替换所有内容）或 PATCH（仅替换你提供的内容）进行另一个请求。通过将 id 提供给端点（/api/objects/214），我们确保更新正确的剑：

>>> data = {"db_key": "An even SHINIER sword", "db_location": 50}
>>> response = requests.put("https://www.mygame.com/api/objects/214",
                            data=data, auth=("Anotherusername", "mypassword"))
>>> response.json()
{"db_key": "An even SHINIER sword", "id": 214, "db_location": 50, ...}

在大多数情况下，你不会用 Python 向后端发出 API 请求，而是通过某个前端应用程序使用 JavaScript 发出请求。有许多 JavaScript 库可以简化从前端发出请求的过程，例如 AXIOS，或使用原生的 Fetch。

定制 API¶

总体而言，阅读 Django Rest Framework ViewSets 和其文档的其他部分是扩展和定制 API 的必要条件。

查看 Website 页面，了解如何覆盖代码、模板和静态文件。

API 模板（用于网页显示）位于 evennia/web/api/templates/rest_framework/（必须命名为这样以允许覆盖原始 REST 框架模板）。
静态文件位于 evennia/web/api/static/rest_framework/
API 代码位于 evennia/web/api/ - 这里的 url.py 文件负责收集所有视图类。

与其他网页组件不同，mygame/web/api/ 没有预先设置的 urls.py。这是因为模型与 API 的注册与 REST API 功能紧密集成。最简单的方法可能是复制 evennia/web/api/urls.py 并在原地修改。

目录

上一个主题

下一个主题

链接

Evennia REST API¶

使用方法¶

定制 API¶