Hub documentation

إدارة التحكم في وصول المستخدم برمجياً

Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

إدارة التحكم في وصول المستخدم برمجياً

يصف هذا الدليل كيفية إدارة أدوار أعضاء المنظمة وانتماءات مجموعات الموارد عبر واجهة برمجة تطبيقات Hub: تغيير دور العضو في المنظمة وتعيينات مجموعات الموارد، وإدراج قائمة بمجموعات الموارد، وإضافة المستخدمين إلى المجموعات، وسير العمل الدُفعي.

جدول المحتويات:

تغيير دور العضو عبر واجهة برمجة التطبيقات — تعيين دور العضو في المنظمة وتعيينات مجموعات الموارد (عضو واحد لكل طلب).
واجهة برمجة تطبيقات مجموعات الموارد — قائمة مجموعات الموارد وإضافة المستخدمين إليها.
إعداد الانضمام التلقائي عبر واجهة برمجة التطبيقات — تفعيل أو تعطيل الانضمام التلقائي على مجموعة موارد.
دعوة متعاونين خارجيين عبر واجهة برمجة التطبيقات — دعوة مستخدمين من خارج المنظمة إلى مجموعة موارد.
تغيير نوع حساب العضو عبر واجهة برمجة التطبيقات — تحويل العضو إلى متعاون خارجي، أو العكس.

تغيير دور العضو عبر واجهة برمجة التطبيقات

يمكنك تغيير دور العضو في المنظمة (بدون وصول / قراءة / مساهم / كتابة / مسؤول) و، بشكل اختياري، أدواره في مجموعات الموارد باستخدام واجهة برمجة تطبيقات Hub. تحدّث الواجهة عضوًا واحدًا لكل طلب. لتغيير أدوار عدة أعضاء، استدعِ الواجهة في حلقة (أمثلة أدناه).

مرجع OpenAPI: PUT /api/organizations/{name}/members/{username}/role

المتطلبات

يجب أن يكون لدى مؤسستك خطة اشتراك (مثل Team أو Enterprise). وإلا، فسيُرجع نقطة النهاية 402.
يجب أن تكون مصادقًا كعضو في المنظمة مع إذن Write (أو Admin) على المنظمة.
يجب أن يكون المستخدم المستهدف عضوًا بالفعل في المنظمة.

عنوان URL الأساسي والمصادقة

عنوان URL الأساسي: https://huggingface.co
Authentication: أرسل رمزك في ترويسة الطلب:
```
Authorization: Bearer <your_access_token>
```
أنشئ رمزًا دقيقًا مع إذن «الوصول للكتابة إلى إعدادات المنظمات / إدارة الأعضاء» محدد النطاق لمنظمتك في https://huggingface.co/settings/tokens.

نقطة نهاية تغيير دور العضو

طلب

PUT /api/organizations/{org_name}/members/{username}/role
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "role": "read",
  "resourceGroups": []
}

Path parameters
- org_name: اسم المنظمة المختصر (مثل my-org).
- username: اسم المستخدم username على Hugging Face للعضو الذي تريد تغيير دوره.
Body
- role (إلزامي): دور العضو على مستوى المنظمة. أحد الخيارات التالية: "no_access"، "read"، "contributor"، "write"، أو "admin".
- resourceGroups (اختياري: مصفوفة من تعيينات مجموعات الموارد لهذا المستخدم. كل عنصر:
  - id: معرّف مجموعة الموارد (سلسلة سداسية عشرية من 24 حرفًا؛ احصل على المعرّفات من واجهة برمجة التطبيقات الخاصة بقائمة مجموعات الموارد).
  - role: الدور في مجموعة الموارد تلك: "read"، "contributor"، "write"، "admin"، أو "inherit".
- إذا أهملت resourceGroups أو مررت []، يُزال المستخدم من جميع مجموعات الموارد. لتغيير دور المنظمة فقط مع إبقاء مجموعات الموارد دون تغيير، مرّ عضويات مجموعة الموارد الحالية (فجسم الطلب يضبط دائمًا كلا من دور المنظمة وقائمة مجموعات الموارد).

مثال (curl) – تعيين دور المنظمة إلى “قراءة” دون مجموعات موارد (يزيل أي مجموعة كان المستخدم عضوًا فيها سابقًا)

curl -s -X PUT \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role":"read","resourceGroups":[]}' \
  "https://huggingface.co/api/organizations/my-org/members/member1/role"

مثال (curl) – تعيين دور المنظمة وأدوار مجموعة الموارد (يتجاوز أي مجموعات حالية)

curl -s -X PUT \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"role":"write","resourceGroups":[{"id":"507f1f77bcf86cd799439011","role":"read"}]}' \
  "https://huggingface.co/api/organizations/my-org/members/member2/role"

استجابة النجاح: الحالة 200 OK؛ المحتوى: { "success": true }.

الأخطاء الشائعة

400 — جسم غير صالح (مثل دور غير صالح أو id لمجموعة موارد غير صالحة).
402 — لا تملك المنظمة خطة اشتراك.
403 — غير مسموح (على سبيل المثال، تفتقر إلى صلاحية Write في المنظمة، أو أن مجموعة الموارد ليست ضمن المنظمة).
404 — لم يتم العثور على المنظمة أو المستخدم.

تحديث أعضاء متعددين

تُغيّر واجهة برمجة التطبيقات عضوًا واحدًا لكل طلب. لا يوجد نقطة نهاية للعمليات الجماعية. لتحديث العديد من الأعضاء، استدعِ نقطة النهاية مرةً واحدةً لكل اسم مستخدم (مثلًا من قائمة أو ملف CSV).

مثال: Bash – تكرار على أسماء المستخدمين، الدور نفسه للجميع

ORG_NAME="my-org"
ROLE="read"
for username in member1 member2 member3 member4; do
  echo "Setting $username to $ROLE ..."
  curl -s -w "\n%{http_code}" -X PUT \
    -H "Authorization: Bearer $HF_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"role\":\"$ROLE\",\"resourceGroups\":[]}" \
    "https://huggingface.co/api/organizations/$ORG_NAME/members/$username/role"
  echo ""
done

مثال: بايثون – التكرار على أسماء المستخدمين

import os
import requests

BASE_URL = "https://huggingface.co"
HF_TOKEN = os.environ.get("HF_TOKEN", "")

def change_member_role(org_name: str, username: str, role: str, resource_groups: list | None = None):
    payload = {"role": role, "resourceGroups": resource_groups or []}
    r = requests.put(
        f"{BASE_URL}/api/organizations/{org_name}/members/{username}/role",
        headers={"Authorization": f"Bearer {HF_TOKEN}", "Content-Type": "application/json"},
        json=payload,
    )
    if r.status_code != 200:
        raise RuntimeError(f"{r.status_code}: {r.text}")
    return r.json()

org_name = "my-org"
role = "read"
for username in ["member1", "member2", "member3", "member4"]:
    print(f"Setting {username} to {role} ... ", end="")
    try:
        change_member_role(org_name, username, role)
        print("OK")
    except Exception as e:
        print(f"Failed: {e}")

لأدوار مختلفة لكل مستخدم، قم بالتكرار على أزواج (username, role) (مثلًا من ملف CSV) واستدعِ change_member_role لكل زوج.

واجهة برمجة تطبيقات مجموعات الموارد

تتيح لك نقاط النهاية التالية عرض مجموعات الموارد وإضافة مستخدمين إليها. لتغيير دور العضو الموجود على مستوى المؤسسة أو تعييناته في مجموعات الموارد، راجع تغيير دور العضو عبر واجهة برمجة التطبيقات أعلاه.

مرجع OpenAPI: مجموعات الموارد

جدول المحتويات — أساليب واجهة برمجة التطبيقات:

الهدف	القسم
إضافة العديد من المستخدمين إلى مجموعة موارد واحدة	إضافة مستخدمين إلى مجموعة موارد
أضف نفس المستخدمين إلى عدة مجموعات موارد	الإضافة الدفعية عبر التكرار على واجهة برمجة التطبيقات
إضافة مستخدمين مختلفين لكل مجموعة	الإضافة الدفعية عبر التكرار على واجهة برمجة التطبيقات

عنوان URL الأساسي والمصادقة

عنوان URL الأساسي: https://huggingface.co
Authentication: استخدم أحد ما يلي:
- Access token (recommended for scripts): أنشئ رمزًا دقيقًا (fine-grained token) يحمل صلاحية «الوصول للكتابة إلى إعدادات المنظمات / إدارة الأعضاء» محددًا النطاق لمنظمتك في https://huggingface.co/settings/tokens. أرِحه في ترويسة الطلب:
```
Authorization: Bearer <your_access_token>
```
- ملف تعريف الجلسة: عند الاستدعاء من متصفح أو أداة تشارك نفس الجلسة مع واجهة Hub، يُرسل ملف التعريف تلقائيًا.

قائمة مجموعات الموارد

احصل على جميع مجموعات الموارد التي يمكنك إدارتها للمنظمة. استخدم هذا للحصول على id لكل مجموعة لاستدعاءات add-users.

طلب

GET /api/organizations/{org_name}/resource-groups
Authorization: Bearer <your_access_token>

مثال (curl)

curl -s -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/organizations/my-org/resource-groups"

مثال على الاستجابة (مقتطعة)

[
  {
    "id": "507f1f77bcf86cd799439011",
    "name": "Cohort 2024",
    "description": "Members in this group",
    "users": [...],
    "repos": [...]
  }
]

استخدم id لكل مجموعة موارد عند إضافة المستخدمين.

إضافة مستخدمين إلى مجموعة موارد

أضف مستخدمًا واحدًا أو أكثر إلى مجموعة موارد واحدة في طلب واحد. يمكنك إرسال عدة مستخدمين في نفس الطلب.

طلب

POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/users
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "users": [
    { "user": "member1", "role": "read" },
    { "user": "member2", "role": "read" },
    { "user": "member3", "role": "write" }
  ]
}

Path parameters
- org_name: اسم المنظمة المختصر (مثل my-org).
- resource_group_id: المعرف id لمجموعة الموارد (سلسلة سداسية عشرية من 24 حرفًا من نقطة النهاية الخاصة بالقائمة).
Body
- users: مصفوفة من الكائنات. يجب أن يحتوي كل كائن على:
  - user: اسم المستخدم username في Hugging Face (إلزامي).
  - role: أحد "read"، "contributor"، "write"، "admin"، أو "inherit".

مثال (curl)

curl -s -X POST \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"users":[{"user":"member1","role":"read"},{"user":"member2","role":"read"}]}' \
  "https://huggingface.co/api/organizations/my-org/resource-groups/507f1f77bcf86cd799439011/users"

نجاح: الحالة 200 OK؛ المحتوى هو كائن مجموعة الموارد المحدّثة (يتضمن المستخدمين الجدد في users).

الأخطاء الشائعة:

400 — على سبيل المثال، المستخدم غير موجود، أسماء مستخدمين مكررة، أو جسم غير صالح.
403 — غير مسموح (على سبيل المثال، غير موجود في المنظمة، أو موجود بالفعل في مجموعة الموارد). سيوضح الرسالة ما إذا كان المستخدمون غير موجودين في المنظمة أو موجودين بالفعل في المجموعة.

إضافة الأعضاء عبر البريد الإلكتروني (حل بديل)

يقبل منفذ add-users أسماء مستخدمين على Hugging Face فقط، وليس عناوين البريد الإلكتروني. إذا كان لديك قائمة من عناوين البريد الإلكتروني (مثل عناوين بريد الأعضاء)، يمكنك أولاً تحويل البريد الإلكتروني إلى اسم مستخدم، ثم استدعاء واجهة برمجة تطبيقات add-users.

لاحظ أن تصفية البريد الإلكتروني تعمل فقط عندما يتطابق نطاق البريد الإلكتروني مع أحد النطاقات المسموح بها للمنظمة: نطاق بريد المنظمة (الإعدادات → الحساب → نطاق بريد المنظمة) و/أو نطاقات SSO المسموح بها للمنظمة (إذا كان SSO مُهيأً).

الخطوة 1 – تحويل البريد الإلكتروني إلى اسم مستخدم

GET /api/organizations/{org_name}/members?email={email}&limit=1
Authorization: Bearer <your_access_token>

الاستجابة عبارة عن مصفوفة من الأعضاء؛ لكل عضو user (اسم المستخدم). استخدم user في استدعاء إضافة المستخدمين.

الخطوة 2 – الإضافة إلى مجموعة الموارد

استخدم اسم المستخدم من الخطوة 1 في طلب إضافة مستخدمين عادي:

POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/users
Content-Type: application/json
Body: { "users": [{ "user": "<username from step 1>", "role": "read" }] }

مثال: بريد إلكتروني واحد (bash)

ORG_NAME="my-org"
RG_ID="507f1f77bcf86cd799439011"
EMAIL="member@org.com"

# Step 1: look up member by email (domain must match org's Organization email domain or SSO allowed domains)
MEMBERS=$(curl -s -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/organizations/$ORG_NAME/members?email=$EMAIL&limit=1")
USERNAME=$(echo "$MEMBERS" | jq -r '(.[0] // {} | .user // "")')
if [ -z "$USERNAME" ]; then
  echo "No member found for $EMAIL"
  exit 1
fi
# Step 2: add to resource group
curl -s -X POST -H "Authorization: Bearer $HF_TOKEN" -H "Content-Type: application/json" \
  -d "{\"users\":[{\"user\":\"$USERNAME\",\"role\":\"read\"}]}" \
  "https://huggingface.co/api/organizations/$ORG_NAME/resource-groups/$RG_ID/users"

مثال: رسائل بريد إلكتروني متعددة في حلقة (بايثون)

import os
import requests

BASE = "https://huggingface.co"
ORG = "my-org"
RG_ID = "507f1f77bcf86cd799439011"
ROLE = "read"
headers = {"Authorization": f"Bearer {os.environ['HF_TOKEN']}", "Content-Type": "application/json"}

emails = ["member1@org.com", "member2@org.com"]
for email in emails:
    # Step 1: resolve email → username (email domain must match org's Organization email domain or SSO allowed domains)
    r = requests.get(f"{BASE}/api/organizations/{ORG}/members", params={"email": email, "limit": 1}, headers=headers)
    r.raise_for_status()
    members = r.json()
    if not members:
        print(f"No member found for {email}")
        continue
    username = members[0]["user"]
    # Step 2: add that user to the resource group
    add_r = requests.post(
        f"{BASE}/api/organizations/{ORG}/resource-groups/{RG_ID}/users",
        headers=headers,
        json={"users": [{"user": username, "role": ROLE}]},
    )
    if add_r.status_code == 200:
        print(f"Added {username} ({email})")
    else:
        print(f"Failed {email}: {add_r.status_code} {add_r.text}")

إذا كان المستخدم موجودًا مسبقًا في مجموعة الموارد، فإن استدعاء الإضافة يعيد 403؛ ويبلّغ السكربت عن ذلك كإخفاق، ويمكنك تخطي أو تجاهل ذلك الحالتين إن رغبت.

قيود: لا يُطبَّق مرشّح البريد الإلكتروني إلا عندما تكون لدى المنظمة نطاق بريد إلكتروني للمنظمة و/أو نطاقات مسموح بها لتسجيل الدخول الأحادي (SSO) مُعيّنة، ويتطابق نطاق البريد الإلكتروني مع أحد هذه النطاقات. وإلا، فلا يمكنك البحث بالبريد الإلكتروني عبر واجهة برمجة التطبيقات (API) الخاصة بالأعضاء؛ بل ستحتاج إلى مصدر آخر للربط بين البريد الإلكتروني واسم المستخدم (مثل دليلك الخاص).

الإضافة الدفعية عن طريق التكرار على واجهة برمجة التطبيقات

يمكنك إضافة العديد من المستخدمين إلى مجموعة موارد واحدة في طلب واحد أو بضع طلبات (مثل تقسيم قائمة أسماء المستخدمين إلى أجزاء)، أو إضافة المستخدمين إلى عدة مجموعات موارد عن طريق التكرار على المجموعات واستدعاء نقطة نهاية إضافة المستخدمين لكل مجموعة.

مثال: Bash – مجموعة واحدة، مستخدمون متعددون في طلب واحد

#!/bin/bash
# Add a list of users to a single resource group.
# Usage: ./add-users-to-rg.sh <org_name> <resource_group_id> <role>

ORG_NAME="${1:-my-org}"
RG_ID="${2:-507f1f77bcf86cd799439011}"
ROLE="${3:-read}"

USERS="member1 member2 member3 member4"
USERS_JSON=$(echo "$USERS" | tr ' ' '\n' | while read u; do
  [ -n "$u" ] && echo "{\"user\":\"$u\",\"role\":\"$ROLE\"}"
done | paste -sd ',' -)

curl -s -w "\nHTTP_STATUS:%{http_code}" -X POST \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"users\":[$USERS_JSON]}" \
  "https://huggingface.co/api/organizations/$ORG_NAME/resource-groups/$RG_ID/users"

مثال: Bash – التكرار عبر مجموعات متعددة

# Get group IDs and add users to each
curl -s -H "Authorization: Bearer $HF_TOKEN" \
  "https://huggingface.co/api/organizations/my-org/resource-groups" \
  | jq -r '.[].id' \
  | while read -r RG_ID; do
      [ -z "$RG_ID" ] && continue
      echo "Adding users to resource group $RG_ID ..."
      curl -s -X POST -H "Authorization: Bearer $HF_TOKEN" -H "Content-Type: application/json" \
        -d "{\"users\":[$USERS_JSON]}" \
        "https://huggingface.co/api/organizations/my-org/resource-groups/$RG_ID/users"
    done

مثال: بايثون – إضافة دفعة إلى مجموعة واحدة أو عدة مجموعات

import os
import requests

BASE_URL = "https://huggingface.co"
HF_TOKEN = os.environ.get("HF_TOKEN", "")

def list_resource_groups(org_name: str):
    r = requests.get(
        f"{BASE_URL}/api/organizations/{org_name}/resource-groups",
        headers={"Authorization": f"Bearer {HF_TOKEN}"},
    )
    r.raise_for_status()
    return r.json()

def add_users_to_resource_group(org_name: str, resource_group_id: str, users_with_roles: list):
    """users_with_roles: list of {"user": "username", "role": "read"|"write"|"contributor"|"admin"}"""
    r = requests.post(
        f"{BASE_URL}/api/organizations/{org_name}/resource-groups/{resource_group_id}/users",
        headers={"Authorization": f"Bearer {HF_TOKEN}", "Content-Type": "application/json"},
        json={"users": users_with_roles},
    )
    if r.status_code != 200:
        raise RuntimeError(f"Add users failed {r.status_code}: {r.text}")
    return r.json()

# Example: same users added to every resource group
org_name = "my-org"
role = "read"
usernames = ["member1", "member2", "member3"]
users_with_roles = [{"user": u, "role": role} for u in usernames]

for rg in list_resource_groups(org_name):
    add_users_to_resource_group(org_name, rg["id"], users_with_roles)

في حالة وجود قائمة طويلة من أسماء المستخدمين، قسّمها إلى أجزاء (مثل 50 اسمًا لكل طلب) واستدعِ الواجهة البرمجية مرة واحدة لكل جزء لتجنب أحجام الطلبات الكبيرة أو انتهاء المهلة الزمنية.

ملاحظات مهمة

أسماء المستخدمين فقط — تقبل واجهة برمجة التطبيقات أسماء المستخدمين الخاصة بـ Hugging Face، وليس عناوين البريد الإلكتروني. تحتاج إلى إنشاء خريطة من البريد الإلكتروني إلى اسم المستخدم (مثلًا من دليلك أو قائمة أعضاء المنظمة) قبل استدعاء واجهة برمجة التطبيقات.
يجب أن يكون المستخدمون أعضاء في المنظمة — يجب أن يكون كل مستخدم في الطلب عضوًا بالفعل في المنظمة. وإلا، سيعيد الطلب 403 مع رسالة تفيد بأن بعض المستخدمين ليسوا أعضاء في المنظمة.
القدرة على التكرار دون تغيير النتيجة — إذا كان المستخدم موجودًا مسبقًا في مجموعة الموارد، فقد يعيد الخادم الخلفي 403 لذلك الطلب. يمكن لسكربتك التقاط الأخطاء والمواصلة، أو تخطي المستخدمين الموجودين مسبقًا في المجموعة إذا جلبت أولًا قائمة users الخاصة بالمجموعة.
حدود المعدل — عند التعامل مع دفعات كبيرة، يُنصح بإضافة تأخير قصير بين الطلبات (مثل 0.5–1 ثانية) لتجنب تجاوز حدود المعدل.
نطاق الرمز — يجب أن يتمتع رمز الوصول بالصلاحيات الكافية للمنظمة (عادةً ما تكون على الأقل “صلاحية الكتابة في إعدادات المنظمات / إدارة الأعضاء”). أنشئ الرمز واحفظه بأمان؛ لا تلتزم به في نظام التحكم بالإصدارات.

Configuration of auto-join via API

يضيف Auto-join أعضاء المنظمة تلقائيًا إلى مجموعة موارد بدور محدد. يمكنك تفعيله أو تعطيله عبر واجهة برمجة التطبيقات (API)، مع إمكانية اختيار تضمين جميع أعضاء المنظمة أو تضمين أعضاء Read+ فقط.

تفعيل الانضمام التلقائي

POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/settings
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "autoJoin": {
    "enabled": true,
    "role": "read",
    "scope": "read_plus"
  }
}

Path parameters
- org_name: اسم المنظمة المختصر (مثل my-org).
- resource_group_id: معرّف مجموعة الموارد (سلسلة سداسية عشرية من 24 حرفًا؛ احصل على المعرّفات من نقطة نهاية قائمة مجموعات الموارد).
Body
- role: الدور الذي يُسند إلى الأعضاء المضافين تلقائيًا. أحد "read"، "contributor"، "write"، "admin"، أو "inherit".
- scope (اختياري): أعضاء المنظمة الذين سيتم إضافتهم تلقائيًا. استخدم "all" لتضمين جميع أعضاء المنظمة. استخدم "read_plus" لاستبعاد الأعضاء الذين يحملون دور no_access في المنظمة. القيمة الافتراضية هي "all" عند عدم تحديد هذا المعامل.

تفعيل الانضمام التلقائي على مجموعة موارد قائمة يضيف فوراً أعضاء المنظمة الحاليين المطابقين للنطاق المحدد (إضافة رجعية).

تعطيل الانضمام التلقائي

أرسل الطلب نفسه مع "enabled": false. لا يُشترط حقل role عند التعطيل:

POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/settings
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "autoJoin": {
    "enabled": false
  }
}

عدم تفعيل الانضمام التلقائي لا يزيل الأعضاء الذين تم إضافتهم تلقائياً سابقاً. إنه فقط يمنع إضافة أعضاء المنظمة المستقبليين تلقائياً. تبقى الأعضاء الحاليين في مجموعة الموارد.

تعيين حدود الإنفاق عبر واجهة برمجة التطبيقات

تحدد حدود الإنفاق الحد الأقصى للإنفاق الشهري على الحوسبة المرتبط بمجموعة الموارد. اضبطها باستخدام نقطة النهاية الخاصة بالتحديث:

PATCH /api/organizations/{org_name}/resource-groups/{resource_group_id}
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "spendLimits": {
    "total": 500000,
    "spaces": 100000,
    "jobs": 50000
  }
}

Path parameters
- org_name: اسم المنظمة المختصر (مثل my-org).
- resource_group_id: معرّف مجموعة الموارد (سلسلة سداسية عشرية من 24 حرفًا؛ احصل على المعرّفات من نقطة نهاية قائمة مجموعات الموارد).
Body
- spendLimits: حدود شهرية بالسنت. يحدد المثال أعلاه حدًا إجماليًا قدره 5,000 دولار، بمبلغ 1,000 دولار لـ Spaces و500 دولار لـ Jobs.
  - total: الحد الأقصى للإنفاق المجمّع للمجموعة عبر جميع المنتجات.
  - inferenceProviders، spaces، jobs، endpoints: حدود لكل منتج، تُطبَّق فوق الحد الإجمالي. يسود الأضيق من الحدّين.

يتم تحديث المفاتيح التي ترسلها فقط، بينما تحتفظ المفاتيح الأخرى بقيمتها الحالية. أرسل null لإزالة حد:

PATCH /api/organizations/{org_name}/resource-groups/{resource_group_id}
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "spendLimits": {
    "jobs": null
  }
}

مثال (curl)

curl -s -X PATCH \
  -H "Authorization: Bearer $HF_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"spendLimits": {"total": 500000}}' \
  "https://huggingface.co/api/organizations/my-org/resource-groups/507f1f77bcf86cd799439011"

الاستجابة هي مجموعة الموارد المحدّثة، بما في ذلك spendLimits الخاصة بها.

دعوة متعاونين خارجيين عبر واجهة برمجة التطبيقات

تتيح الدعوات الخارجية لمسؤولي مجموعة الموارد دعوة مستخدمين من خارج المنظمة إلى مجموعة الموارد. ينضم المدعوون كمشاركين خارجيين بدور no_access على مستوى المنظمة. ويُحتسبون ضمن عدد المقاعد المدفوعة في منطمتك.

تفعيل الدعوات الخارجية

يمكن للمسؤولين في المنظمة تفعيل الإعداد باستخدام:

POST /api/organizations/{org_name}/resource-groups/settings
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "allowExternalInvites": true
}

Body
- allowExternalInvites (اختياري): ما إذا كان بإمكان مسؤولي مجموعة الموارد دعوة مستخدمين من خارج المنظمة.
- minRoleToCreate (اختياري): أدنى دور تنظيمي مطلوب لـ إنشاء مجموعات الموارد.

تُترك الحقول المحذوفة دون تغيير. استخدم GET /api/organizations/{org_name}/resource-groups/settings لقراءة الإعدادات الحالية.

دعوة مستخدم

POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/invite
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "username": "partner-user",
  "role": "read"
}

Path parameters
- org_name: اسم المنظمة المختصر (مثل my-org).
- resource_group_id: معرّف مجموعة الموارد (سلسلة سداسية عشرية من 24 حرفًا؛ احصل على المعرّفات من نقطة نهاية قائمة مجموعات الموارد).
Body
- username: اسم مستخدم لمستخدم حالي على Hugging Face ليس عضوًا في المنظمة بعد. لإضافة عضو إلى المنظمة، استخدم إضافة مستخدمين إلى مجموعة موارد بدلاً من ذلك.
- role: الدور الذي يحصل عليه المدعو في مجموعة الموارد، "read" أو "write".

يصل المستخدم دعوة عبر البريد الإلكتروني ويحصل على الوصول إلى مجموعة الموارد بعد قبوله الدعوة.

إدارة الدعوات المعلقة

قائمة: GET /api/organizations/{org_name}/resource-groups/{resource_group_id}/invitations
إعادة الإرسال: POST /api/organizations/{org_name}/resource-groups/{resource_group_id}/invitation/{invitation_id}/resend
إلغاء: DELETE /api/organizations/{org_name}/resource-groups/{resource_group_id}/invitation/{invitation_id}

يمكنك أيضًا الاطلاع على مواصفة OpenAPI الكاملة

الأخطاء الشائعة:

403 — الدعوات الخارجية غير مفعّلة للمنظمة.
409 — المستخدم عضو بالفعل في المنظمة، أو لديه بالفعل دعوة معلقة إليها.

تغيير نوع حساب العضو عبر واجهة برمجة التطبيقات

تحويل عضو في المنظمة إلى مشارك خارجي (لا يتطلب تسجيل دخول موحّد)، أو إعادته إلى عضو. يتطلب اشتراكًا مدفوعًا وصلاحيات Write (أو Admin) على المنظمة. غير متاح في المنظمات التي لديها مستخدمون مُدارون، حيث يتم إنشاء الأعضاء عبر SCIM.

لا يؤدي تغيير نوع حساب المستخدم إلى تغيير دوره. راجع تغيير دور العضو عبر واجهة برمجة التطبيقات لتغيير دور المستخدم.

PUT /api/organizations/{org_name}/members/{username}/account-type
Authorization: Bearer <your_access_token>
Content-Type: application/json

{
  "accountType": "external"
}

Body
- accountType: "external" لتحويل العضو إلى متعاون خارجي، أو "member" لتحويله مرة أخرى.

Update on GitHub

←التحكم المتقدم في الوصول (مجموعات الموارد) فحص البرمجيات الخبيثة→