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

# إنشاء الموصلات

> تعلم كيفية إنشاء وتكوين الموصلات برمجياً

<Tip>
  هذا دليل متقدم لأتمتة إنشاء الموصلات.
  نوصي بشدة بتجربة لوحة الإدارة أو File Ingestion API أولاً.
</Tip>

للاطلاع على الموصلات المتاحة، راجع [صفحة الموصلات](/admins/connectors).

## الدليل

انتقل إلى قسم [الكود الكامل](#full-code) إذا كنت لا تريد الدليل التفصيلي.

في هذا المثال، سنؤتمر إنشاء موصلات Jira لمجموعة من المشاريع.

**ستحتاج إلى مفتاح API للمسؤول لمتابعة هذا الدليل.**

<Steps>
  <Step title="جهّز طلبك">
    <CodeGroup>
      ```python Python theme={null}
      import requests

      API_BASE_URL = "https://cloud.gorbit.app/api"   # أو نطاقك الخاص
      API_KEY = "YOUR_KEY_HERE"

      headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json"
      }
      ```

      ```bash Shell theme={null}
      API_BASE_URL="https://cloud.gorbit.app/api"
      API_KEY="YOUR_KEY_HERE"
      ```
    </CodeGroup>
  </Step>

  <Step title="جهّز ConnectorSpecificConfig">
    كل نوع موصل لديه `ConnectorSpecificConfig` مختلف. للعثور على التكوين الصحيح،
    ابحث عن الموصل ذي الصلة في
    [`backend/gorbit/connectors/`](https://github.com/gorbit-dot-app/gorbit/tree/main/backend/gorbit/connectors).

    بالنسبة لـ Jira، بما أننا نفهرس مجموعة مختارة من المشاريع، بدلاً من جميع المشاريع،
    سنحتاج إلى تحديد `jira_base_url`، و `project_key`، واختيارياً `comment_email_blacklist`.

    ```json JSON theme={null}
    {
      "jira_base_url": "string",
      "project_key": "string | null",
      "comment_email_blacklist": ["string"] | null
    }
    ```

    <Note>
      `ConnectorSpecificConfig` هي نفس الحقول التي تملؤها في لوحة الإدارة عند إنشاء موصل.
    </Note>
  </Step>

  <Step title="جهّز بيانات الموصل">
    بالإضافة إلى `ConnectorSpecificConfig`،
    نحتاج أيضاً إلى تلبية مخطط كائن `ConnectorUpdateRequest`. راجع [المفاهيم الأساسية:
    الموصلات](/developers/core_concepts#connectors) للحصول على مزيد من التفاصيل.

    في هذا المثال، سنضبط `access_type`، و `name`، و `source`، و `input_type`، و `refresh_freq`، و `prune_freq`.

    <CodeGroup>
      ```python Python theme={null}
      connector_payload = {
        "name": f"jira-{project_key}",
        "source": "jira",
        "input_type": "poll",
        "access_type": "PUBLIC",
        "connector_specific_config": {
          "jira_base_url": JIRA_BASE_URL,
          "project_key": project_key,
          "comment_email_blacklist": ["legal@company.com"]
        },
        "refresh_freq": 3600,  # تحديث كل ساعة (3600 ثانية)
        "prune_freq": 86400,   # تقليم كل يوم (86400 ثانية)
      }
      ```

      ```json JSON theme={null}
      {
        "name": "jira-TECH",
        "source": "jira",
        "input_type": "poll",
        "access_type": "PUBLIC",
        "connector_specific_config": {
          "jira_base_url": "https://your-company.atlassian.net",
          "project_key": "TECH",
          "comment_email_blacklist": ["legal@company.com"]
        },
        "refresh_freq": 3600,
        "prune_freq": 86400
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="قم بإجراء الطلب">
    <Tip>
      احفظ معرف الموصل من الاستجابة! ستحتاجه لاحقاً.
    </Tip>

    <CodeGroup>
      ```python Python expandable theme={null}
      import requests
      import json
      from datetime import datetime

      PROJECTS_TO_INDEX = [
        "TECH",
        "SALES",
        "OPS",
      ]

      JIRA_BASE_URL = "https://your-company.atlassian.net"
      connector_ids = []

      for project_key in PROJECTS_TO_INDEX:
        connector_payload = {
          "name": f"jira-{project_key}",
          "source": "jira",
          "input_type": "poll",
          "access_type": "PUBLIC",
          "connector_specific_config": {
            "jira_base_url": JIRA_BASE_URL,
            "project_key": project_key,
            "comment_email_blacklist": ["legal@company.com"]
          },
          "refresh_freq": 3600,  # تحديث كل ساعة (3600 ثانية)
          "prune_freq": 86400,   # تقليم كل يوم (86400 ثانية)
        }

        response = requests.post(
          f"{API_BASE_URL}/manage/admin/connector",
          headers=headers,
          json=connector_payload
        )

        if response.status_code == 200:
          connector_data = response.json()
          connector_id = connector_data.get('id')
          connector_ids.append(connector_id)
          print(f"تم إنشاء موصل للمشروع {project_key} بنجاح")
          print(f"معرف الموصل: {connector_id}")
        else:
          print(f"فشل إنشاء موصل للمشروع {project_key}")
          print(f"الحالة: {response.status_code}")
          print(f"الخطأ: {response.text}")
      ```

      ```bash Shell expandable theme={null}
      # إنشاء موصل للمشروع TECH
      curl -X POST "${API_BASE_URL}/manage/admin/connector" \
        -H "Authorization: Bearer ${API_KEY}" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "jira-TECH",
          "source": "jira",
          "input_type": "poll",
          "access_type": "PUBLIC",
          "connector_specific_config": {
            "jira_base_url": "https://your-company.atlassian.net",
            "project_key": "TECH",
            "comment_email_blacklist": ["legal@company.com"]
          },
          "refresh_freq": 3600,
          "prune_freq": 86400
        }'

      # إنشاء موصل للمشروع SALES
      curl -X POST "${API_BASE_URL}/manage/admin/connector" \
        -H "Authorization: Bearer ${API_KEY}" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "jira-SALES",
          "source": "jira",
          "input_type": "poll",
          "access_type": "PUBLIC",
          "connector_specific_config": {
            "jira_base_url": "https://your-company.atlassian.net",
            "project_key": "SALES",
            "comment_email_blacklist": ["legal@company.com"]
          },
          "refresh_freq": 3600,
          "prune_freq": 86400
        }'

      # إنشاء موصل للمشروع OPS
      curl -X POST "${API_BASE_URL}/manage/admin/connector" \
        -H "Authorization: Bearer ${API_KEY}" \
        -H "Content-Type: application/json" \
        -d '{
          "name": "jira-OPS",
          "source": "jira",
          "input_type": "poll",
          "access_type": "PUBLIC",
          "connector_specific_config": {
            "jira_base_url": "https://your-company.atlassian.net",
            "project_key": "OPS",
            "comment_email_blacklist": ["legal@company.com"]
          },
          "refresh_freq": 3600,
          "prune_freq": 86400
        }'
      ```
    </CodeGroup>
  </Step>

  <Step title="ابحث عن بيانات الاعتماد للموصل">
    أسهل طريقة لإنشاء بيانات اعتماد هي في لوحة الإدارة.

    * انقر على إضافة موصل
    * اختر الموصل ذي الصلة
    * اتبع التعليمات لإنشاء بيانات اعتماد

    بمجرد إنشاء بيانات الاعتماد، سيتم عرض معرف بيانات الاعتماد لك.

    قد لا تتطلب بعض الموصلات بيانات اعتماد مثل موصلات الملفات والويب. `credential_id:
            0` هو بيانات اعتماد فارغة افتراضية يمكنك استخدامها لهذه الموصلات.

    لعرض قائمة بيانات الاعتماد الخاصة بك، يمكنك استخدام نقطة النهاية `GET manage/admin/credential`.

    <CodeGroup>
      ```python Python theme={null}
      response = requests.get(
        f"{API_BASE_URL}/manage/admin/credential",
        headers=headers
      )

      credentials = response.json()
      jira_credential_id = next(cred for cred in credentials if cred['source'] == 'jira')['id']
      ```

      ```bash Shell theme={null}
      curl -X GET "${API_BASE_URL}/manage/admin/credential" \
        -H "Authorization: Bearer ${API_KEY}" \
        -H "Content-Type: application/json"
      ```
    </CodeGroup>
  </Step>

  <Step title="اربط بيانات الاعتماد بالموصل">
    <Note>
      إذا لم تقم بهذه الخطوة، فإن `Connector` الخاص بك لم يتم إنشاؤه بالكامل ولن تراه في لوحة الإدارة!
    </Note>

    <CodeGroup>
      ```python Python theme={null}
      for connector_id in connector_ids:
        try:
          response = requests.put(
            f"{API_BASE_URL}/manage/admin/connector/{connector_id}/credential/{jira_credential_id}",
            headers=headers,
          )

          if response.status_code == 200:
            print(f"تم ربط بيانات الاعتماد بالموصل {connector_id} بنجاح")
          else:
            print(f"فشل ربط بيانات الاعتماد بالموصل {connector_id}")
            print(f"الحالة: {response.status_code}. الخطأ: {response.text}")
        except Exception as e:
          print(f"فشل ربط بيانات الاعتماد بالموصل {connector_id}: {e}")
      ```

      ```bash Shell theme={null}
      # استبدل CONNECTOR_ID و CREDENTIAL_ID بالقيم الفعلية
      curl -X PUT "${API_BASE_URL}/manage/admin/connector/CONNECTOR_ID/credential/CREDENTIAL_ID" \
        -H "Authorization: Bearer ${API_KEY}" \
        -H "Content-Type: application/json"
      ```
    </CodeGroup>
  </Step>
</Steps>

## الكود الكامل

<CodeGroup>
  ```python Python expandable theme={null}
  import requests
  import json
  from datetime import datetime

  # التكوين
  API_BASE_URL = "https://cloud.gorbit.app/api"   # أو نطاقك الخاص
  API_KEY = "YOUR_KEY_HERE"

  headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json"
  }

  # المشاريع لإنشاء موصلات لها
  PROJECTS_TO_INDEX = [
    "TECH",
    "SALES",
    "OPS",
  ]

  JIRA_BASE_URL = "https://your-company.atlassian.net"
  connector_ids = []

  # الخطوة 1: إنشاء موصلات لكل مشروع
  print("جاري إنشاء الموصلات...")
  for project_key in PROJECTS_TO_INDEX:
    connector_payload = {
      "name": f"jira-{project_key}",
      "source": "jira",
      "input_type": "poll",
      "access_type": "PUBLIC",
      "connector_specific_config": {
        "jira_base_url": JIRA_BASE_URL,
        "project_key": project_key,
        "comment_email_blacklist": ["legal@company.com"]
      },
      "refresh_freq": 3600,  # تحديث كل ساعة (3600 ثانية)
      "prune_freq": 86400,   # تقليم كل يوم (86400 ثانية)
    }

    response = requests.post(
      f"{API_BASE_URL}/manage/admin/connector",
      headers=headers,
      json=connector_payload
    )

    if response.status_code == 200:
      connector_data = response.json()
      connector_id = connector_data.get('id')
      connector_ids.append(connector_id)
      print(f"تم إنشاء موصل للمشروع {project_key} بنجاح")
      print(f"معرف الموصل: {connector_id}")
    else:
      print(f"فشل إنشاء موصل للمشروع {project_key}")
      print(f"الحالة: {response.status_code}")
      print(f"الخطأ: {response.text}")

  # الخطوة 2: الحصول على بيانات الاعتماد
  print("\nجاري جلب بيانات الاعتماد...")
  response = requests.get(
    f"{API_BASE_URL}/manage/admin/credential",
    headers=headers
  )

  if response.status_code == 200:
    credentials = response.json()
    # البحث عن بيانات اعتماد Jira (يفترض أن لديك واحدة تم إنشاؤها)
    jira_credential = next((cred for cred in credentials if cred['source'] == 'jira'), None)

    if jira_credential:
      jira_credential_id = jira_credential['id']
      print(f"تم العثور على بيانات اعتماد Jira بالمعرف: {jira_credential_id}")
    else:
      print("لم يتم العثور على بيانات اعتماد Jira. يرجى إنشاء واحدة في لوحة الإدارة أولاً.")
      exit(1)
  else:
    print(f"فشل جلب بيانات الاعتماد: {response.status_code}")
    print(f"الخطأ: {response.text}")
    exit(1)

  # الخطوة 3: ربط بيانات الاعتماد بالموصلات
  print("\nجاري ربط بيانات الاعتماد بالموصلات...")
  for connector_id in connector_ids:
    try:
      response = requests.put(
        f"{API_BASE_URL}/manage/admin/connector/{connector_id}/credential/{jira_credential_id}",
        headers=headers,
      )

      if response.status_code == 200:
        print(f"تم ربط بيانات الاعتماد بالموصل {connector_id} بنجاح")
      else:
        print(f"فشل ربط بيانات الاعتماد بالموصل {connector_id}")
        print(f"الحالة: {response.status_code}. الخطأ: {response.text}")
    except Exception as e:
      print(f"فشل ربط بيانات الاعتماد بالموصل {connector_id}: {e}")

  print(f"\nاكتمل! تم إنشاء {len(connector_ids)} موصل بالمعرفات: {connector_ids}")
  ```

  ```bash Shell expandable theme={null}
  #!/bin/bash

  # التكوين
  API_BASE_URL="https://cloud.gorbit.app/api"
  API_KEY="YOUR_KEY_HERE"

  # مصفوفة المشاريع لإنشاء موصلات لها
  PROJECTS=("TECH" "SALES" "OPS")
  JIRA_BASE_URL="https://your-company.atlassian.net"

  # مصفوفة لتخزين معرفات الموصلات
  CONNECTOR_IDS=()

  echo "جاري إنشاء الموصلات..."

  # الخطوة 1: إنشاء موصلات لكل مشروع
  for PROJECT in "${PROJECTS[@]}"; do
    echo "جاري إنشاء موصل للمشروع: $PROJECT"

    RESPONSE=$(curl -s -w "\n%{http_code}" -X POST "${API_BASE_URL}/manage/admin/connector" \
      -H "Authorization: Bearer ${API_KEY}" \
      -H "Content-Type: application/json" \
      -d "{
        \"name\": \"jira-${PROJECT}\",
        \"source\": \"jira\",
        \"input_type\": \"poll\",
        \"access_type\": \"PUBLIC\",
        \"connector_specific_config\": {
          \"jira_base_url\": \"${JIRA_BASE_URL}\",
          \"project_key\": \"${PROJECT}\",
          \"comment_email_blacklist\": [\"legal@company.com\"]
        },
        \"refresh_freq\": 3600,
        \"prune_freq\": 86400
      }"
    )

    HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
    BODY=$(echo "$RESPONSE" | head -n -1)

    if [ "$HTTP_CODE" -eq 200 ]; then
      CONNECTOR_ID=$(echo "$BODY" | jq -r '.id')
      CONNECTOR_IDS+=("$CONNECTOR_ID")
      echo "تم إنشاء موصل للمشروع $PROJECT بنجاح"
      echo "معرف الموصل: $CONNECTOR_ID"
    else
      echo "فشل إنشاء موصل للمشروع $PROJECT"
      echo "الحالة: $HTTP_CODE"
      echo "الخطأ: $BODY"
    fi
  done

  # الخطوة 2: الحصول على بيانات الاعتماد
  echo -e "\nجاري جلب بيانات الاعتماد..."
  CRED_RESPONSE=$(curl -s -w "\n%{http_code}" -X GET "${API_BASE_URL}/manage/admin/credential" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json")

  CRED_HTTP_CODE=$(echo "$CRED_RESPONSE" | tail -n1)
  CRED_BODY=$(echo "$CRED_RESPONSE" | head -n -1)

  if [ "$CRED_HTTP_CODE" -eq 200 ]; then
    JIRA_CREDENTIAL_ID=$(echo "$CRED_BODY" | jq -r '.[] | select(.source == "jira") | .id' | head -n1)

    if [ "$JIRA_CREDENTIAL_ID" != "null" ] && [ -n "$JIRA_CREDENTIAL_ID" ]; then
      echo "تم العثور على بيانات اعتماد Jira بالمعرف: $JIRA_CREDENTIAL_ID"
    else
      echo "لم يتم العثور على بيانات اعتماد Jira. يرجى إنشاء واحدة في لوحة الإدارة أولاً."
      exit 1
    fi
  else
    echo "فشل جلب بيانات الاعتماد: $CRED_HTTP_CODE"
    echo "الخطأ: $CRED_BODY"
    exit 1
  fi

  # الخطوة 3: ربط بيانات الاعتماد بالموصلات
  echo -e "\nجاري ربط بيانات الاعتماد بالموصلات..."
  for CONNECTOR_ID in "${CONNECTOR_IDS[@]}"; do
    echo "جاري ربط بيانات الاعتماد بالموصل: $CONNECTOR_ID"

    ASSOC_RESPONSE=$(curl -s -w "\n%{http_code}" -X PUT "${API_BASE_URL}/manage/admin/connector/${CONNECTOR_ID}/credential/${JIRA_CREDENTIAL_ID}" \
      -H "Authorization: Bearer ${API_KEY}" \
      -H "Content-Type: application/json")

    ASSOC_HTTP_CODE=$(echo "$ASSOC_RESPONSE" | tail -n1)
    ASSOC_BODY=$(echo "$ASSOC_RESPONSE" | head -n -1)

    if [ "$ASSOC_HTTP_CODE" -eq 200 ]; then
      echo "تم ربط بيانات الاعتماد بالموصل $CONNECTOR_ID بنجاح"
    else
      echo "فشل ربط بيانات الاعتماد بالموصل $CONNECTOR_ID"
      echo "الحالة: $ASSOC_HTTP_CODE"
      echo "الخطأ: $ASSOC_BODY"
    fi
  done

  echo -e "\nاكتمل! تم إنشاء ${#CONNECTOR_IDS[@]} موصل بالمعرفات: ${CONNECTOR_IDS[*]}"
  ```
</CodeGroup>