# خادم Webhooks

تُعدّ Webhooks أساسًا للميزات المتعلقة بـ MLOps. فهي تتيح لك الاستماع إلى التغييرات الجديدة في مستودعات محددة، أو في جميع المستودعات التابعة لمستخدمين أو منظمات معينة ترغب في متابعتها. لمعرفة المزيد حول Webhooks في Huggingface Hub، يمكنك قراءة [دليل](https://huggingface.co/docs/hub/webhooks) Webhooks.

> [!TIP]
> اطّلع على هذا [الدليل](../guides/webhooks_server) للحصول على شرح خطوة بخطوة حول كيفية إعداد خادم الويب هوك الخاص بك ونشره كـ Space.

> [!WARNING]
> هذه ميزة تجريبية. وهذا يعني أننا ما زلنا نعمل على تحسين واجهة برمجة التطبيقات (API). قد تُدخل تغييرات كاسرة في المستقبل دون إشعار مسبق. تأكد من تثبيت إصدار `huggingface_hub` في متطلباتك. يتم إطلاق تحذير عند استخدام ميزة تجريبية. يمكنك تعطيله عن طريق تعيين `HF_HUB_DISABLE_EXPERIMENTAL_WARNING=1` كمتغير بيئة.

## الخادم

الخادم هو تطبيق [Gradio](https://gradio.app/). يحتوي على واجهة مستخدم لعرض التعليمات لك أو لمستخدميك، وواجهة برمجية (API) للاستماع إلى webhooks. تنفيذ نقطة نهاية webhook بسيطة إلى حد ما، إذ يكفي تزيين دالة (decorating a function). يمكنك بعد ذلك تصحيح الأخطاء عن طريق إعادة توجيه webhooks إلى جهازك (باستخدام نفق Gradio) قبل نشره على Space.

### WebhooksServer[[huggingface_hub.WebhooksServer]]

#### huggingface_hub.WebhooksServer[[huggingface_hub.WebhooksServer]]

```python
huggingface_hub.WebhooksServer(*args, **kwargs)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_server.py#L37)

**المعاملات:**

ui (`gradio.Blocks`، اختياري) : مثال على واجهة Gradio المستخدم (UI) ليتم استخدامه كصفحة الهبوط الخاصة بالمساحة. إذا كان `None`، يتم إنشاء واجهة تعرض تعليمات حول الخطافات (webhooks) المُهيأة.

webhook_secret (`str`, اختياري) : مفتاح سري للتحقق من طلبات webhook الواردة. يمكنك تعيين هذا القيمة إلى أي سر تريده طالما قمت بتكوينه أيضًا في [لوحة إعدادات webhooks](https://huggingface.co/settings/webhooks). كما يمكنك تعيين هذا القيمة كمتغير البيئة `WEBHOOK_SECRET`. إذا لم يتم توفير أي سر، فإن نقاط نهاية webhook تُفتح دون أي أمان.

تتيح لك فئة [WebhooksServer()](/docs/huggingface_hub/v2.4.0/ar/package_reference/webhooks_server#huggingface_hub.WebhooksServer) إنشاء نسخة من تطبيق Gradio يمكنها استقبال خطافات Huggingface. يمكن تسجيل هذه الخطافات باستخدام مُزيّن `add_webhook()`. تُضاف نقاط نهاية الخطافات إلى التطبيق كنقطة نهاية POST إلى موجّه FastAPI. بعد تسجيل جميع الخطافات، يجب استدعاء طريقة `launch` لبدء التطبيق.

يُوصى بقبول [WebhookPayload](/docs/huggingface_hub/v2.4.0/ar/package_reference/webhooks_server#huggingface_hub.WebhookPayload) كحجة أولى لدالة الويب هوك. وهو نموذج Pydantic يحتوي على جميع المعلومات المتعلقة بحدث الويب هوك. سيتم تحليل البيانات تلقائياً من أجلك.

اطّلع على [دليل webhooks](../guides/webhooks_server) للحصول على شرح خطوة بخطوة حول كيفية إعداد WebhooksServer الخاص بك ونشره على Space.

> [!WARNING]
> `WebhooksServer` تجريبي. قد تتغير واجهته البرمجية (API) في المستقبل.

> [!WARNING]
> يجب أن يكون `gradio` مثبّتًا لاستخدام `WebhooksServer` (`pip install --upgrade gradio`).

مثال:

```python
import gradio as gr
from huggingface_hub import WebhooksServer, WebhookPayload

with gr.Blocks() as ui:
    ...

app = WebhooksServer(ui=ui, webhook_secret="my_secret_key")

@app.add_webhook("/say_hello")
async def hello(payload: WebhookPayload):
    return {"message": "hello"}

app.launch()
```

### @webhook_endpoint[[huggingface_hub.webhook_endpoint]]

#### huggingface_hub.webhook_endpoint[[huggingface_hub.webhook_endpoint]]

```python
huggingface_hub.webhook_endpoint(path: str | None = None)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_server.py#L221)

**المعاملات:**

path (`str`, اختياري) : مسار URL لتسجيل دالة webhook. إذا لم يُقدَّم، فسيتم استخدام اسم الدالة كمسار. في جميع الأحوال، تُسجَّل جميع webhooks تحت `/webhooks`.

مُزيِّن لبدء [WebhooksServer()](/docs/huggingface_hub/v2.4.0/ar/package_reference/webhooks_server#huggingface_hub.WebhooksServer) وتسجيل الدالة المُزيَّنة كنقطة نهاية webhook.

هذا مساعد للبدء بسرعة. إذا كنت بحاجة إلى مرونة أكبر (صفحة هبوط مخصصة أو سري Webhook)، يمكنك استخدام [WebhooksServer()](/docs/huggingface_hub/v2.4.0/ar/package_reference/webhooks_server#huggingface_hub.WebhooksServer) مباشرةً. يمكنك تسجيل نقاط نهاية Webhook متعددة (على نفس الخادم) من خلال استخدام هذا الزخّار (decorator) عدة مرات.

اطّلع على [دليل webhooks](../guides/webhooks_server) للحصول على شرح خطوة بخطوة حول كيفية إعداد خادمك ونشره على Space.

> [!WARNING]
> `webhook_endpoint` تجريبي. قد تتغير واجهته البرمجية (API) في المستقبل.

> [!WARNING]
> يجب أن يكون `gradio` مثبّتًا لاستخدام `webhook_endpoint` (`pip install --upgrade gradio`).

أمثلة: الاستخدام الافتراضي هو تسجيل دالة كنقطة نهاية لـ webhook. سيُستخدم اسم الدالة كمسار. سيُشغَّل الخادم تلقائيًا عند الخروج (أي في نهاية السكربت).

```python
from huggingface_hub import webhook_endpoint, WebhookPayload

@webhook_endpoint
async def trigger_training(payload: WebhookPayload):
    if payload.repo.type == "dataset" and payload.event.action == "update":
        # Trigger a training job if a dataset is updated
        ...

# Server is automatically started at the end of the script.
```

الاستخدام المتقدم: تسجيل دالة كنقطة نهاية (endpoint) لـ webhook وبدء الخادم يدويًا. يكون هذا مفيدًا إذا كنت تشغّله في دفتر ملاحظات (notebook).

```python
from huggingface_hub import webhook_endpoint, WebhookPayload

@webhook_endpoint
async def trigger_training(payload: WebhookPayload):
    if payload.repo.type == "dataset" and payload.event.action == "update":
        # Trigger a training job if a dataset is updated
        ...

# Start the server manually
trigger_training.launch()
```

## حمولة[[huggingface_hub.WebhookPayload]]

[WebhookPayload](/docs/huggingface_hub/v2.4.0/ar/package_reference/webhooks_server#huggingface_hub.WebhookPayload) هي بنية البيانات الرئيسية التي تحتوي على الحمولة (payload) القادمة من Webhooks. وهي فئة `pydantic` مما يجعل استخدامها مع FastAPI سهلاً للغاية. إذا مررتها كمعامل إلى نقطة نهاية webhook، فسيتم التحقق منها وتحليلها تلقائياً ككائن Python.

لمزيد من المعلومات حول حمولة webhooks، يمكنك الرجوع إلى [دليل](https://huggingface.co/docs/hub/webhooks#webhook-payloads) حمولة Webhooks.

#### huggingface_hub.WebhookPayload[[huggingface_hub.WebhookPayload]]

```python
huggingface_hub.WebhookPayload(event: WebhookPayloadEvent, repo: WebhookPayloadRepo, discussion: huggingface_hub._webhooks_payload.WebhookPayloadDiscussion | None = None, comment: huggingface_hub._webhooks_payload.WebhookPayloadComment | None = None, webhook: WebhookPayloadWebhook, movedTo: huggingface_hub._webhooks_payload.WebhookPayloadMovedTo | None = None, updatedRefs: list[huggingface_hub._webhooks_payload.WebhookPayloadUpdatedRef] | None = None)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L129)

### WebhookPayload[[huggingface_hub.WebhookPayload]]

#### huggingface_hub.WebhookPayload[[huggingface_hub.WebhookPayload]]

```python
huggingface_hub.WebhookPayload(event: WebhookPayloadEvent, repo: WebhookPayloadRepo, discussion: huggingface_hub._webhooks_payload.WebhookPayloadDiscussion | None = None, comment: huggingface_hub._webhooks_payload.WebhookPayloadComment | None = None, webhook: WebhookPayloadWebhook, movedTo: huggingface_hub._webhooks_payload.WebhookPayloadMovedTo | None = None, updatedRefs: list[huggingface_hub._webhooks_payload.WebhookPayloadUpdatedRef] | None = None)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L129)

### WebhookPayloadComment[[huggingface_hub.WebhookPayloadComment]]

#### huggingface_hub.WebhookPayloadComment[[huggingface_hub.WebhookPayloadComment]]

```python
huggingface_hub.WebhookPayloadComment(id: str, author: ObjectId, hidden: bool, content: str | None = None, url: WebhookPayloadUrl)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L94)

### WebhookPayloadDiscussion[[huggingface_hub.WebhookPayloadDiscussion]]

#### huggingface_hub.WebhookPayloadDiscussion[[huggingface_hub.WebhookPayloadDiscussion]]

```python
huggingface_hub.WebhookPayloadDiscussion(id: str, num: int, author: ObjectId, url: WebhookPayloadUrl, title: str, isPullRequest: bool, status: typing.Literal['closed', 'draft', 'open', 'merged'], changes: huggingface_hub._webhooks_payload.WebhookPayloadDiscussionChanges | None = None, pinned: bool | None = None)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L101)

### WebhookPayloadDiscussionChanges[[huggingface_hub.WebhookPayloadDiscussionChanges]]

#### huggingface_hub.WebhookPayloadDiscussionChanges[[huggingface_hub.WebhookPayloadDiscussionChanges]]

```python
huggingface_hub.WebhookPayloadDiscussionChanges(base: str, mergeCommitId: str | None = None)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L89)

### WebhookPayloadEvent[[huggingface_hub.WebhookPayloadEvent]]

#### huggingface_hub.WebhookPayloadEvent[[huggingface_hub.WebhookPayloadEvent]]

```python
huggingface_hub.WebhookPayloadEvent(action: typing.Literal['create', 'delete', 'move', 'update'], scope: str)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L84)

### WebhookPayloadMovedTo[[huggingface_hub.WebhookPayloadMovedTo]]

#### huggingface_hub.WebhookPayloadMovedTo[[huggingface_hub.WebhookPayloadMovedTo]]

```python
huggingface_hub.WebhookPayloadMovedTo(name: str, owner: ObjectId)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L75)

### WebhookPayloadRepo[[huggingface_hub.WebhookPayloadRepo]]

#### huggingface_hub.WebhookPayloadRepo[[huggingface_hub.WebhookPayloadRepo]]

```python
huggingface_hub.WebhookPayloadRepo(id: str, owner: ObjectId, head_sha: str | None = None, name: str, private: bool, subdomain: str | None = None, tags: list[str] | None = None, type: typing.Literal['dataset', 'model', 'space'], url: WebhookPayloadUrl)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L112)

### WebhookPayloadUrl[[huggingface_hub.WebhookPayloadUrl]]

#### huggingface_hub.WebhookPayloadUrl[[huggingface_hub.WebhookPayloadUrl]]

```python
huggingface_hub.WebhookPayloadUrl(web: str, api: str | None = None)
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L70)

### WebhookPayloadWebhook[[huggingface_hub.WebhookPayloadWebhook]]

#### huggingface_hub.WebhookPayloadWebhook[[huggingface_hub.WebhookPayloadWebhook]]

```python
huggingface_hub.WebhookPayloadWebhook(id: str, version: typing.Literal[3])
```

[المصدر](https://github.com/huggingface/huggingface_hub/blob/v2.4.0/src/huggingface_hub/_webhooks_payload.py#L80)