监听器

有时候为请求设置监听器非常有用，让你能够实现那些需要在应用中“发生某事”时被调用的功能。为此我们添加了两种类型的监听器。

捕获监听器（Capture Listener）

举个例子，假设每次向 ‘/logs’ 路由发起请求时，我的代码都会执行一个任务，用于检查新日志是否与旧日志不同。那么，我们来看看这该如何实现：

import squarecloud as square
from squarecloud import Endpoint

@app.capture(endpoint=Endpoint.logs())
async def on_logs_request(before, after):
    if after != before:
        print(f'New logs!!! {after}')

async def main():
    client = square.Client('your api key')
    app = await client.app('application_id')

    await app.logs()  # True
    await app.logs()  # False

如上所示，通过在函数上使用 app.capture 装饰器，每当向装饰器中指定的 endpoint 发起请求时，该函数就会被调用。可接受的 endpoint 有 APP_STATUS、LOGS 或 BACKUP。该函数应接受两个参数：

before（表示请求之前的状态）
after（表示请求之后的状态）

before 和 after 返回的数据类型取决于监听器所“监听”的 endpoint。如果是 APP_STATUS 路由，将接收到 StatusData；LOGS 将接收到 LogsData；BACKUP 将接收到 BackupData。正如你在上面的示例中可能已经注意到的，第一次进行日志之间的比较时，after != before 返回 True。这正是因为此时 after 等于 LogsData(logs='')，因为内部缓存中还没有存储任何内容。

关于该装饰器的补充信息

如果你使用 discord.py 或它的某个分支（你很可能在用），你应该知道区分事件的是装饰器所包装的函数的名称，但在这里则不同。为了知道装饰器需要“监听”哪个 API 路由，我们使用 endpopint 参数，它接收一个 Endpoint 类，因此装饰器所包装的函数名称由你自行决定。
装饰器所包装的对象实际上可以是任何可调用对象。这包括普通函数、协程，甚至是类（会调用 __init__）。
如果 endpoint 不是 [Endpoint.app_status()]、[Endpoint.logs()] 或 [Endpoint.backup()]，则只会返回一个 response 参数（类型为 squarecloud.http.Response）。

你可以使用 avoid_listener=True 参数，使应用监听器不被调用。

请求监听器（Request Listener）

“请求监听器”所做的事情基本相同。但在这里你使用的是 [Client]，并且所有 endpoint 返回的都是 squarecloud.http.Response 对象。

import squarecloud as square
from squarecloud import Endpoint

@client.on_request(endpoint=Endpoint.logs())
async def on_logs_request(response):
    print(1, response)

async def main():
    client = square.Client('your api key')
    await client.get_logs(app_id='application_id')  # 1, Response(success)

传递额外参数

你可以向某些方法传递名为 extra 的关键字参数，它将被传递给你的监听器。

import squarecloud as square
from squarecloud import Endpoint

@client.on_request(Endpoint.status())
async def get_extra_param(before, after, extra: dict[str, str]):
    print(extra)

async def main():
    client = square.Client('your api key')
    await client.app_status('application_id', extra={'name': 'robertinho'})

在你的项目中使用 pydantic，可以在监听器中获得一些很酷的特性，请查看使用 pydantic

服务

Runtimes

平台

故障排除

CLI

SDKs

Changelog

捕获监听器（Capture Listener）

请求监听器（Request Listener）

传递额外参数

​捕获监听器（Capture Listener）

​请求监听器（Request Listener）

​传递额外参数

捕获监听器（Capture Listener）

请求监听器（Request Listener）

传递额外参数