كيفية استخدام مهارات Claude البرمجية لطلبات API والشبكات (جلب البيانات)

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

لماذا تعتبر مهارات شبكات واجهة برمجة التطبيقات (API) مهمة لسير عمل التطوير

يقضي كل مطور ساعات في أعمال واجهة برمجة التطبيقات المتكررة: إعداد الرؤوس لـ OAuth 2.0، وتطبيق التراجع الأسي (exponential backoff) لنقاط النهاية ذات المعدل المحدود، وكتابة أدوات حماية النوع (type guards) لاستجابات JSON غير المتوقعة. هذه المهام عرضة للخطأ ومرتبطة ارتباطًا وثيقًا بخدمات معينة، مما يجعل اختبارها وصيانتها صعبًا. تعمل مهارات Claude Code على تجريد هذا التعقيد في أدوات قابلة للاختبار وذات إصدارات، يمكن لمساعدك الذكي استدعائها باللغة الطبيعية.

التحول هو من استدعاءات واجهة برمجة التطبيقات الأمرية إلى جلب البيانات التصريحي. بدلًا من كتابة fetch(url, { headers: {...} })، فإنك تصف النية: “جلب بيانات المستخدم من واجهة برمجة تطبيقات GitHub باستخدام الرمز المميز من المتغيرات البيئية (ENV) وإرجاع نتائج ذات أنواع محددة.” تتولى المهارة إدارة بيانات الاعتماد ومنطق إعادة المحاولة وتحليل الاستجابة، مع إرجاع بيانات ذات أنواع قوية يمكن لتطبيقك استهلاكها فورًا.

💡

هل تريد أداة رائعة لاختبار واجهة برمجة التطبيقات (API) تولد توثيقًا جميلًا لواجهة برمجة التطبيقات؟

هل تريد منصة متكاملة وشاملة لفريق المطورين الخاص بك للعمل معًا بـ أقصى إنتاجية؟

يلبي Apidog جميع متطلباتك، و يحل محل Postman بسعر أكثر معقولية!

زر

إعداد مهارة جلب البيانات في Claude Code

الخطوة 1: تثبيت Claude Code وتكوين MCP

إذا لم تقم بتثبيت واجهة سطر الأوامر (CLI) لـ Claude Code:

npm install -g @anthropic-ai/claude-code
claude --version  # Should show >= 2.0.70

أنشئ دليل وملف تكوين MCP:

# macOS/Linux
mkdir -p ~/.config/claude-code
touch ~/.config/claude-code/config.json

# Windows
mkdir %APPDATA%\claude-code
echo {} > %APPDATA%\claude-code\config.json

الخطوة 2: استنساخ وبناء مهارة جلب البيانات

توفر مهارة جلب البيانات الرسمية أنماطًا لطلبات REST و GraphQL و HTTP العامة.

git clone https://github.com/anthropics/skills.git
cd skills/skills/data-fetching
npm install
npm run build

يقوم هذا بتجميع معالجات TypeScript إلى dist/index.js.

الخطوة 3: تكوين MCP لتحميل المهارة

عدّل ~/.config/claude-code/config.json:

{
  "mcpServers": {
    "data-fetching": {
      "command": "node",
      "args": ["/absolute/path/to/skills/data-fetching/dist/index.js"],
      "env": {
        "DEFAULT_TIMEOUT": "30000",
        "MAX_RETRIES": "3",
        "RATE_LIMIT_PER_MINUTE": "60",
        "CREDENTIALS_STORE": "~/.claude-credentials.json"
      }
    }
  }
}

هام:

استخدم مسارات مطلقة لـ args
قم بتكوين متغيرات البيئة:
DEFAULT_TIMEOUT: مهلة الطلب بالمللي ثانية
MAX_RETRIES: عدد محاولات إعادة المحاولة لأخطاء 5xx
RATE_LIMIT_PER_MINUTE: عتبة التحديد
CREDENTIALS_STORE: مسار ملف بيانات الاعتماد المشفرة

الخطوة 4: إعداد مخزن بيانات الاعتماد

أنشئ ملف بيانات الاعتماد لتجنب كتابة الرموز المميزة مباشرةً في الكود:

# Create encrypted credentials store
mkdir -p ~/.claude
echo '{}' > ~/.claude/credentials.json
chmod 600 ~/.claude/credentials.json

أضف رموز واجهة برمجة التطبيقات الخاصة بك:

{
  "github": {
    "token": "ghp_your_github_token_here",
    "baseUrl": "https://api.github.com"
  },
  "slack": {
    "token": "xoxb-your-slack-token",
    "baseUrl": "https://slack.com/api"
  },
  "custom-api": {
    "token": "Bearer your-jwt-token",
    "baseUrl": "https://api.yourcompany.com",
    "headers": {
      "X-API-Version": "v2"
    }
  }
}

تقوم المهارة بقراءة هذا الملف عند بدء التشغيل وحقن بيانات الاعتماد في الطلبات.

الخطوة 5: التحقق من التثبيت

claude

بمجرد التحميل، قم بتشغيل:

/list-tools

يجب أن ترى:

Available tools:
- data-fetching:rest-get
- data-fetching:rest-post
- data-fetching:rest-put
- data-fetching:rest-delete
- data-fetching:graphql-query
- data-fetching:graphql-mutation
- data-fetching:raw-http

أنماط طلبات واجهة برمجة التطبيقات الأساسية

1. طلبات RESTful GET

الأداة: data-fetching:rest-get
حالة الاستخدام: جلب البيانات من نقاط نهاية REST مع المصادقة والترقيم والتخزين المؤقت

المعلمات:

service: المفتاح المطابق لمخزن بيانات الاعتماد (github, slack, custom-api)
endpoint: مسار واجهة برمجة التطبيقات (على سبيل المثال، /users، /repos/owner/name)
params: كائن معلمات الاستعلام
cache: مدة صلاحية ذاكرة التخزين المؤقت بالثواني (اختياري)
transform: تعبير JMESPath لتحويل الاستجابة

مثال: جلب مستودعات مستخدم GitHub

استخدم rest-get لجلب المستودعات للمستخدم "anthropics" من واجهة برمجة تطبيقات GitHub، بما في ذلك الترقيم لـ 100 عنصر لكل صفحة، وإرجاع الاسم والوصف و stargazers_count فقط.

التنفيذ المتولد:

// المعالج ينفذ:
const response = await fetch('https://api.github.com/users/anthropics/repos', {
  headers: {
    'Authorization': 'token ghp_your_github_token_here',
    'Accept': 'application/vnd.github.v3+json'
  },
  params: {
    per_page: 100,
    page: 1
  }
});

// تحويل باستخدام JMESPath
const transformed = jmespath.search(response, '[*].{name: name, description: description, stars: stargazers_count}');
return transformed;

استخدام Claude Code:

claude --skill data-fetching \
  --tool rest-get \
  --params '{"service": "github", "endpoint": "/users/anthropics/repos", "params": {"per_page": 100}, "transform": "[*].{name: name, description: description, stars: stargazers_count}"}'

2. طلبات POST/PUT/DELETE

الأداة: data-fetching:rest-post / rest-put / rest-delete
حالة الاستخدام: إنشاء الموارد أو تحديثها أو حذفها

المعلمات:

service: مفتاح مخزن بيانات الاعتماد
endpoint: مسار واجهة برمجة التطبيقات
body: حمولة الطلب (كائن أو سلسلة JSON)
headers: رؤوس إضافية
idempotencyKey: لسلامة إعادة المحاولة

مثال: إنشاء مشكلة في GitHub

استخدم rest-post لإنشاء مشكلة في مستودع anthorpics/claude بعنوان "طلب ميزة: التخزين المؤقت لأداة MCP"، مع نص يحتوي على الوصف، وتسميات ["تحسين", "mcp"].

التنفيذ:

await fetch('https://api.github.com/repos/anthropics/claude/issues', {
  method: 'POST',
  headers: {
    'Authorization': 'token ghp_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: "Feature Request: MCP Tool Caching",
    body: "Description of the feature...",
    labels: ["enhancement", "mcp"]
  })
});

3. استعلامات GraphQL

الأداة: data-fetching:graphql-query
حالة الاستخدام: جلب بيانات معقدة ذات علاقات متداخلة

المعلمات:

service: مفتاح مخزن بيانات الاعتماد
query: سلسلة استعلام GraphQL
variables: كائن متغيرات الاستعلام
operationName: عملية مسماة

مثال: جلب مشاكل المستودع مع التعليقات

استخدم graphql-query لجلب أحدث 10 مشاكل مفتوحة من مستودع anthorpics/skills، بما في ذلك العنوان، المؤلف، عدد التعليقات، والتسميات.

query RecentIssues($owner: String!, $repo: String!, $limit: Int!) {
  repository(owner: $owner, name: $repo) {
    issues(first: $limit, states: [OPEN], orderBy: {field: CREATED_AT, direction: DESC}) {
      nodes {
        title
        author { login }
        comments { totalCount }
        labels(first: 5) { nodes { name } }
      }
    }
  }
}

المعلمات:

{
  "service": "github",
  "query": "query RecentIssues($owner: String!, $repo: String!, $limit: Int!) { ... }",
  "variables": {
    "owner": "anthropics",
    "repo": "skills",
    "limit": 10
  }
}

4. طلبات HTTP الخام

الأداة: data-fetching:raw-http
حالة الاستخدام: الحالات الهامشية التي لا تغطيها أدوات REST/GraphQL

المعلمات:

url: عنوان URL الكامل
method: طريقة HTTP
headers: كائن الرأس
body: نص الطلب
timeout: تجاوز المهلة الافتراضية

مثال: تسليم الويب هوك (Webhook) برؤوس مخصصة

استخدم raw-http لإرسال POST إلى https://hooks.slack.com/services/YOUR/WEBHOOK/URL مع حمولة JSON تحتوي على {text: "Deployment complete"}، ورأس مخصص X-Event: deployment-success.

سيناريوهات الشبكات المتقدمة

معالجة الترقيم

تكتشف المهارة تلقائيًا أنماط الترقيم:

// تحليل رأس ارتباط GitHub
const linkHeader = response.headers.get('Link');
if (linkHeader) {
  const nextUrl = parseLinkHeader(linkHeader).next;
  if (nextUrl && currentPage < maxPages) {
    return {
      data: currentData,
      nextPage: currentPage + 1,
      hasMore: true
    };
  }
}

اطلب جميع الصفحات:

استخدم rest-get لجلب جميع المستودعات للمستخدم "anthropics"، مع معالجة الترقيم تلقائيًا حتى لا توجد صفحات أخرى.

تعيد المهارة مصفوفة مسطحة لجميع النتائج.

تحديد المعدل ومنطق إعادة المحاولة

قم بتكوين سلوك إعادة المحاولة لكل طلب:

{
  "service": "github",
  "endpoint": "/rate_limit",
  "maxRetries": 5,
  "retryDelay": "exponential",
  "retryOn": [429, 500, 502, 503, 504]
}

تطبق المهارة التراجع الأسي مع التذبذب (jitter):

const delay = Math.min(
  (2 ** attempt) * 1000 + Math.random() * 1000,
  30000
);
await new Promise(resolve => setTimeout(resolve, delay));

إدارة الطلبات المتزامنة

دفعة طلبات واجهة برمجة التطبيقات المتعددة بكفاءة:

استخدم rest-get لجلب التفاصيل للمستودعات: ["claude", "skills", "anthropic-sdk"]، مع تنفيذ الطلبات بالتزامن بحد أقصى 3 اتصالات متوازية.

تستخدم المهارة p-limit لتحديد عدد الطلبات المتزامنة:

import pLimit from 'p-limit';
const limit = pLimit(3); // 3 متزامن كحد أقصى

const results = await Promise.all(
  repos.map(repo =>
    limit(() => fetchRepoDetails(repo))
  )
);

اعتراض الطلبات والمحاكاة

للاختبار، اعترض الطلبات دون الوصول إلى واجهات برمجة تطبيقات حقيقية:

// في تكوين المهارة
"env": {
  "MOCK_MODE": "true",
  "MOCK_FIXTURES_DIR": "./test/fixtures"
}

الآن تعيد الطلبات بيانات محاكاة من ملفات JSON:

// test/fixtures/github/repos/anthropics.json
[
  {"name": "claude", "description": "AI assistant", "stars": 5000}
]

تطبيق عملي: بناء لوحة تحكم GitHub

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

استخدم rest-get لجلب جميع المستودعات من GitHub للمنظمة "anthropics"، بما في ذلك الوصف الكامل، عدد النجوم، عدد التفرعات، وعدد المشاكل المفتوحة. قم بتخزين النتائج مؤقتًا لمدة 5 دقائق.

الخطوة 2: إثراء ببيانات المساهمين

لكل مستودع، اجلب كبار المساهمين:

استخدم rest-get لجلب إحصائيات المساهمين للمستودع "anthropics/claude"، وقيدها على أفضل 10 مساهمين، واستخرج اسم المستخدم (login) وعدد المساهمات.

الخطوة 3: توليد إحصائيات موجزة

ادمج البيانات في Claude Code:

const repos = await fetchAllRepos('anthropics');
const enrichedRepos = await Promise.all(
  repos.map(async (repo) => {
    const contributors = await fetchTopContributors('anthropics', repo.name);
    return { ...repo, topContributors: contributors };
  })
);

return {
  totalStars: enrichedRepos.reduce((sum, r) => sum + r.stars, 0),
  totalForks: enrichedRepos.reduce((sum, r) => sum + r.forks, 0),
  repositories: enrichedRepos
};

الخطوة 4: نشر لوحة التحكم

استخدم rest-post لإنشاء موقع GitHub Pages ببيانات لوحة التحكم باستخدام واجهة برمجة تطبيقات GitHub (API) للتأكيد على فرع gh-pages.

معالجة الأخطاء والمرونة

تقوم المهارة بتصنيف الأخطاء لمعالجتها بشكل صحيح:

// أخطاء 4xx: أخطاء العميل
if (response.status >= 400 && response.status < 500) {
  throw new SkillError('client_error', `طلب غير صالح: ${response.status}`, {
    statusCode: response.status,
    details: await response.text()
  });
}

// أخطاء 5xx: أخطاء الخادم (قابلة لإعادة المحاولة)
if (response.status >= 500) {
  throw new SkillError('server_error', `خطأ في الخادم: ${response.status}`, {
    retryable: true,
    statusCode: response.status
  });
}

// أخطاء الشبكة: فشل الاتصال
if (error.code === 'ECONNREFUSED' || error.code === 'ETIMEDOUT') {
  throw new SkillError('network_error', 'الشبكة غير قابلة للوصول', {
    retryable: true,
    originalError: error.message
  });
}

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

الخلاصة

مهارات Claude Code لشبكات واجهة برمجة التطبيقات (API) تحوّل طلبات HTTP المخصصة إلى أدوات جلب بيانات موثوقة وآمنة من حيث النوع وقابلة للمراقبة. من خلال مركزية إدارة بيانات الاعتماد، وتطبيق عمليات إعادة المحاولة الذكية، وتوفير معالجة منظمة للأخطاء، يمكنك التخلص من أكثر مصادر أخطاء تكامل واجهة برمجة التطبيقات شيوعًا. ابدأ بالأدوات الأساسية الأربع — rest-get، rest-post، graphql-query، و raw-http — ثم وسّعها لحالات الاستخدام الخاصة بك. إن الاستثمار في تكوين المهارات يعود بفوائد فورية في اتساق الكود وسرعة التطوير.

عندما تتفاعل مهارات جلب البيانات الخاصة بك مع واجهات برمجة التطبيقات الداخلية (APIs)، تحقق من صحة نقاط النهاية هذه باستخدام Apidog لضمان أن تكاملاتك المدعومة بالذكاء الاصطناعي تستهلك عقودًا موثوقة.

زر