> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Écouteurs

> Apprenez à utiliser les écouteurs dans votre application avec le SDK Python squarecloud.

Il est parfois très utile de disposer d'écouteurs pour les requêtes, ce qui vous permet d'implémenter des fonctionnalités devant être appelées chaque fois que « quelque chose » se produit dans votre application.

Deux types d'écouteurs ont été ajoutés à cette fin.

## Écouteur de capture

Par exemple, imaginez qu'à chaque fois qu'une requête est effectuée vers la route « /logs », mon code exécute une tâche qui vérifie si les nouveaux logs diffèrent des anciens. Voyons comment cela peut être réalisé :

```python theme={null}
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
```

Comme illustré ci-dessus, en utilisant le décorateur app.capture sur une fonction, cette fonction sera appelée chaque fois qu'une requête est effectuée vers l'endpoint spécifié dans le décorateur. Les endpoints acceptés sont `APP_STATUS`, `LOGS` ou `BACKUP`. Cette fonction doit prendre deux paramètres :

* `before` (représente l'état avant la requête)
* `after` (représente l'état après la requête)

Le type de données renvoyé par `before` et `after` dépend de l'endpoint que l'écouteur « écoute ». S'il s'agit de la route **APP\_STATUS**, il recevra un `StatusData`, **LOGS** recevra un `LogsData` et **BACKUP** recevra un `BackupData`.

Comme vous l'avez peut-être remarqué dans l'exemple ci-dessus, la première fois que la comparaison entre les logs a lieu, `after != before` renvoie True. Cela se produit précisément parce que after est égal à `LogsData(logs='')`, car rien n'est encore stocké dans le cache en interne.

<Accordion title="Informations complémentaires sur ce décorateur">
  * Si vous utilisez discord.py ou l'un de ses forks (c'est probablement le cas), vous devez
    savoir que ce qui différencie les événements est le nom
    des fonctions que le décorateur enveloppe, mais ici c'est différent. Pour savoir
    quelle
    route de l'API le décorateur doit « écouter », nous utilisons le paramètre `endpopint`, qui
    reçoit une classe `Endpoint` ; ainsi, le nom de la fonction que le décorateur
    enveloppe est à votre discrétion.
  * La fonction que le décorateur enveloppe peut en réalité être tout ce qui est
    appelable. Cela inclut les fonctions classiques, les coroutines et même
    les classes (`__init__` sera appelé).
  * Si l'endpoint n'est pas un \[Endpoint.app\_status()], \[Endpoint.logs()] ou \[Endpoint.backup()],
    seul un paramètre `response` (de type `squarecloud.http.Response`) sera
    renvoyé.
</Accordion>

<Tip>
  Vous pouvez utiliser le paramètre `avoid_listener=True` pour que l'écouteur de l'application ne soit pas appelé.
</Tip>

## Écouteur de requête

Les « écouteurs de requête » font pratiquement la même chose. Mais ici, vous utilisez le \[Client], et la valeur de retour de tous les endpoints est un objet `squarecloud.http.Response`.

```python theme={null}
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)
```

## Passer des arguments supplémentaires

Vous pouvez passer à certaines méthodes un argument nommé `extra`, et celui-ci sera transmis à votre écouteur

```python theme={null}
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'})
```

<Tip>Vous pouvez bénéficier de fonctionnalités intéressantes dans les écouteurs en utilisant pydantic dans votre projet, jetez un œil à [utiliser pydantic](./using_pydantic)</Tip>