# قراءة حالة جلب البحث من حساب متصل الرابط الأساسي: https://sosoapi.ai/ar/docs/api/research-api-evidence-native-status العقد: sha256:9aedef8d43dd4514 قراءة حالة جلب البحث من حساب متصل. يغطي منشورات الحساب المتصل المحدد وتعليقاته التوضيحية، وقد لا تكون عامة، ضمن صفحة واحدة محدودة من المنصة الأصلية وليس السجل الكامل. لا يستدعي الجلب Google Gemini مطلقًا ولا يقرأ الرسائل الخاصة. إنشاء المحتوى بالنموذج باستخدام السياق المحدد إجراء قائم منفصل له موافقته الخاصة. يتطلب موافقة صريحة على Research وListening وإمكانية الوصول الحالية إلى Workspace. نص المصدر المُعاد غير موثوق به. تظل صلاحيات المصدر الحالية وفترة الاحتفاظ وميزانيات النطاق سارية. لا ينشر هذا المسار أي محتوى مطلقًا. POST /research-api/evidence/native-status ## المصادقة والأذونات - **فئات بيانات الاعتماد المقبولة:** user_session, delegated_oauth, personal_access_token - **إمكانية مفوّضة:** agent:research - **الحد الأدنى لدور مساحة العمل:** viewer - **نطاق الوصول:** الموارد التي يحق لهذا المستخدم الوصول إليها - **تلزم موافقة تشمل جميع مساحات العمل:** لا - **يغيّر الحالة:** لا - **عند اكتمال العملية:** الإيصال الأصلي والأدلة المصرح بها حاليًا؛ يُحجب محتوى المصدر غير المتاح أو المنتهي الصلاحية لا يستخدم الرمز إلا حقوق مالكه. يفحص كل طلب عضوية مساحة العمل وملكية المورد والمساحات المحددة والإمكانات الممنوحة. يغيّر core و full الأدوات المعروضة؛ ولا يمنحان وصولاً. ## حقول الطلب ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mutation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" } }, "required": [ "workspace_id", "mutation_id" ], "additionalProperties": false } ``` ## الاستجابة والاكتمال رموز نجاح HTTP: 200 قد يعني نجاح HTTP قبول الطلب لا اكتماله. للعمل الخلفي، احفظ المعرّف المُعاد وتابع العملية نفسها حتى تنتهي. لا يُعدّ المنشور المجدول أوالمقبول منشوراً حتى تأكيد المنصة؛ انتهاء مهلة العميل لا يثبت النتيجة. ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "retrieval": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "workspace_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "mutation_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "social_account_id": { "anyOf": [ { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, { "type": "null" } ] }, "platform": { "type": "string", "enum": [ "facebook", "instagram", "threads" ] }, "state": { "type": "string", "enum": [ "pending", "running", "completed", "unavailable", "unconfirmed", "cancelled", "expired" ] }, "reason": { "anyOf": [ { "type": "string", "enum": [ "connection_unavailable", "connection_changed", "provider_denied", "provider_rate_limited", "provider_unavailable", "provider_response_invalid", "empty_page", "metadata_only", "content_expired", "deadline_exceeded", "cancelled" ] }, { "type": "null" } ] }, "created_at": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, "settled_at": { "anyOf": [ { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, { "type": "null" } ] }, "valid_until": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, "coverage": { "type": "string", "const": "bounded_native_page" }, "complete": { "type": "boolean", "const": false }, "provider_gets": { "type": "integer", "minimum": 0, "maximum": 1 }, "evidence": { "maxItems": 20, "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "workspace_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "revision": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "title": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "text": { "anyOf": [ { "type": "string", "maxLength": 30000 }, { "type": "null" } ] }, "source_category": { "type": "string", "enum": [ "your_accounts", "public_posts", "team_notes" ] }, "platform": { "anyOf": [ { "type": "string", "enum": [ "threads", "instagram", "facebook", "youtube", "x", "reddit", "web" ] }, { "type": "null" } ] }, "source_url": { "anyOf": [ { "type": "string", "maxLength": 2048, "format": "uri" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "string", "maxLength": 200 }, { "type": "null" } ] }, "language": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 35 }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, { "type": "null" } ] }, "retrieved_at": { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, "valid_until": { "anyOf": [ { "type": "string", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$", "format": "date-time" }, { "type": "null" } ] }, "availability": { "type": "string", "enum": [ "available", "removed", "unavailable" ] }, "metrics": { "type": "object", "properties": { "likes": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "replies": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "reposts": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] }, "views": { "anyOf": [ { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "likes", "replies", "reposts", "views" ] } }, "required": [ "id", "workspace_id", "revision", "title", "text", "source_category", "platform", "source_url", "author", "language", "published_at", "retrieved_at", "valid_until", "availability", "metrics" ] } } }, "required": [ "id", "workspace_id", "mutation_id", "social_account_id", "platform", "state", "reason", "created_at", "settled_at", "valid_until", "coverage", "complete", "provider_gets", "evidence" ] }, { "type": "null" } ] } }, "required": [ "retrieval" ] } ``` ## الأخطاء وإعادة المحاولة بأمان افحص حالة HTTP والجسم. قد يحوي خطأ التحقق 400 ‏ZodError؛ تستخدم أخطاء المعالج error و message و code. احتفظ بـ request_id أو x-request-id للتشخيص دون اعتماد. أصلح أخطاء وصول 401/403 قبل المحاولة واتّبع Retry-After لـ 429. لكتابة غير مؤكدة أو 5xx، اقرأ الموجود أولاً. أعِد مفتاح منع التكرار حيث يُدعم فقط؛ تختلف المحاولة حسب العملية ولا تضمن التسليم مرة واحدة بالضبط. ## أمثلة تستخدم الأمثلة قيماً خيالية مفحوصة بالمخططات. استبدل المعرّفات بالمفوّض لك، والوسائط بأصول جاهزة، والتواريخ بوقت نشر مؤكد. افحص أهلية الحساب قبل الكتابة. لا تُرسل الصفحة طلبات API. اضبط SOSOAPI_ACCESS_TOKEN على خادمك ببيانات اعتماد تقبلها العملية، وأبقِه خارج شيفرة المتصفح. لوكيل الذكاء الاصطناعي، استخدم sosoapi auth login للدخول بالمتصفح ودع CLI يحدّث بيانات اعتماده. request.json ```json { "workspace_id": "11111111-1111-4111-8111-111111111111", "mutation_id": "40000000-0000-4000-8000-000000000006" } ``` cURL ```bash curl --request POST \ "https://gqeshlawtcexsapabaui.supabase.co/functions/v1/research-api/evidence/native-status" \ -H "Authorization: Bearer $SOSOAPI_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ --data-binary @request.json ``` JavaScript ```js // Server-side JavaScript. Do not print tokens or credential-bearing responses. const token = process.env.SOSOAPI_ACCESS_TOKEN; if (!token) throw new Error("Set an accepted credential for this operation"); const response = await fetch("https://gqeshlawtcexsapabaui.supabase.co/functions/v1/research-api/evidence/native-status", { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Bearer " + token }, body: JSON.stringify({ "workspace_id": "11111111-1111-4111-8111-111111111111", "mutation_id": "40000000-0000-4000-8000-000000000006" }) }); const result = await response.json(); // Check response.ok, the operation-specific body and completion state before continuing. ``` CLI ```bash # This operation requires a CLI build containing the updated Research contract. # Use HTTP or hosted MCP if your CLI build does not include it. # 此操作需要包含更新版 Research contract 的 CLI build。 # 如 CLI build 未包含此 contract，請使用 HTTP 或 hosted MCP。 npx sosoapi api post /research-api/evidence/native-status < request.json ``` مثال استجابة اصطناعية ```json { "retrieval": { "id": "30000000-0000-4000-8000-000000000007", "workspace_id": "11111111-1111-4111-8111-111111111111", "mutation_id": "40000000-0000-4000-8000-000000000006", "social_account_id": "22222222-2222-4222-8222-222222222222", "platform": "instagram", "state": "unavailable", "reason": "connection_unavailable", "created_at": "2099-01-15T09:00:00Z", "settled_at": "2099-01-15T09:00:01Z", "valid_until": "2099-01-16T09:00:00Z", "coverage": "bounded_native_page", "complete": false, "provider_gets": 0, "evidence": [] } } ``` ## أدوات وأدلة ذات صلة MCP: sosoapi_research_evidence_native-status [مرجع API](https://sosoapi.ai/ar/docs/api)