Google Cloud Storage

يحفظ مصدر Google Cloud Storage حاويةً، أو بادئات منها، في مساحة أسماء واحدة. يُقرأ كل ملف كما يُقرأ الرفع، والملف المحذوف من الحاوية يفقد مستنداته.

منح الوصول

يقرأ Conare الحاويات عبر حساب خدمة Google واحد، فلا يُتبادل أي مفتاح. امنحه دور Storage Object Viewer وأنشئ الكائن الفارغ .conare/<organization id>، الذي يثبت أن الحاوية ملكك:

gcloud

gcloud storage buckets add-iam-policy-binding gs://acme-reports \
  --member=serviceAccount:conare-ingest@strong-ward-488314-c4.iam.gserviceaccount.com \
  --role=roles/storage.objectViewer
gcloud storage cp /dev/null gs://acme-reports/.conare/ORG_ID

معاينة الحاوية

curl

curl https://api.conare.ai/sources/gcs/preview \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"bucket": "acme-reports", "prefixes": ["2024/"]}'

ربطها

curl

curl https://api.conare.ai/sources \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "gcs", "namespace": "reports", "bucket": "acme-reports", "prefixes": ["2024/"]}'

الحساب

GET /sources/gcs

Response

{
  "configured": true,
  "role": "roles/storage.objectViewer",
  "service_account": "conare-ingest@strong-ward-488314-c4.iam.gserviceaccount.com"
}

service_account، role: الحساب، والدور الذي تمنحه إياه على حاويتك.
يتوقف المصدر عن المزامنة عند إزالة .conare/<organization id>؛ ويذكر gcs_not_verified الكائن المطلوب إنشاؤه.

المخطط الكامل: الحساب الذي تُمنح له الحاوية.

معاينة حاوية

POST /sources/gcs/preview يسرد ما سيقرؤه مصدر من الحاوية؛ لا يُخزَّن شيء.

Response

{
  "bucket": "acme-reports",
  "bytes": 74,
  "complete": true,
  "objects": 2,
  "prefixes": ["2024/"],
  "sample": ["2024/prices.csv", "2024/site-7.txt"],
  "service_account": "conare-ingest@strong-ward-488314-c4.iam.gserviceaccount.com",
  "skipped": 0,
  "too_large": 0,
  "types": { "csv": 1, "txt": 1 },
  "unsupported": 0
}

الخيار	النوع	الوظيفة
`bucket`	string، مطلوب	اسم الحاوية
`prefixes`	array	حتى 20 بادئة، كلٌّ منها حتى 1,024 حرفًا؛ بدونها تُقرأ الحاوية كاملة

الحقل	المعنى
`objects`، `bytes`	الملفات التي سيقرؤها المصدر، وحجمها
`types`	الملفات حسب النوع؛ `other` لتلك التي لا تكشف نوعها إلا بايتاتها
`skipped`، `unsupported`، `too_large`	المجلدات والكائنات الفارغة؛ الملفات التي لا يقرؤها Conare؛ الملفات الأكبر من 512 MiB
`sample`	حتى 20 اسم ملف
`complete`	`false` عندما تحتوي الحاوية على أكثر من 10,000 كائن أو استغرق سردها أكثر من 10 ثوانٍ

المخطط الكامل: معاينة حاوية.

ربط حاوية

أرسل "type": "gcs" إلى POST /sources؛ تبدأ المزامنة الأولى فورًا، ويمكن لمفتاح مقيّد بمساحة الأسماء ربطها.

Response

{
  "id": "src_4e4abfd7ac248dce3668ef76",
  "kind": "gcs",
  "type": "gcs",
  "namespace": "reports",
  "user": null,
  "name": "gs://acme-reports/2024/",
  "status": "active",
  "health": "ok",
  "display": { "state": "ok" },
  "sync": {
    "state": "queued",
    "run_id": null,
    "phase": null,
    "last_success_at": null,
    "last_failure_at": null,
    "next_run_at": "2026-10-21T22:41:44.768045Z",
    "last_error": null
  },
  "documents": 0,
  "documents_verified_at": null,
  "config": {
    "bucket": "acme-reports",
    "prefixes": ["2024/"],
    "service_account": "conare-ingest@strong-ward-488314-c4.iam.gserviceaccount.com",
    "sync_interval_s": 3600
  },
  "failures": 0,
  "created_at": "2026-10-21T21:41:44.768045Z",
  "updated_at": "2026-10-21T21:41:44.768045Z"
}

الخيار	النوع	الوظيفة
`type`	string، مطلوب	`gcs`
`namespace`	string، مطلوب	مساحة الأسماء التي تُحفظ فيها الملفات
`bucket`	string، مطلوب	اسم الحاوية
`prefixes`	array	حتى 20 بادئة، كلٌّ منها حتى 1,024 حرفًا
`name`	string	اسم عرض، حتى 200 حرف؛ الافتراضي `gs://bucket/prefix`
`sync_interval_s`	integer، الافتراضي 3600	الثواني بين المزامنات، من 900 إلى 604,800 (7 أيام)

الحقل	المعنى
`health`	`ok`؛ `degraded` عندما أجّلت آخر مزامنة عمليات الحذف؛ `failing` عندما فقد الحساب صلاحيته أو فشلت آخر 3 مزامنات
`sync`	`state` (`idle` أو `queued` أو `running`)، `last_success_at`، `last_failure_at`، `next_run_at`، `last_error`
`documents`، `failures`	المستندات التي يحفظها، والملفات التي تعذّر حفظها (أدناه)
`config`	الحاوية والبادئات والحساب والفاصل الزمني

المزامنة وفك الربط

الإجراء	المسار	الإجابة
مزامنة الآن	`POST /sources/:id/sync`	`202` مع `run` الخاص بالمزامنة، أو `409 run_active` أثناء وجود مزامنة في الانتظار أو قيد التشغيل
فك الربط	`DELETE /sources/:id`	`202` مع `run` الذي يحذف مستنداته؛ يصبح المصدر `deleting`، ثم `deleted`

تسرد كل مزامنة محتويات الحاوية وتقرأ الملفات الجديدة والمعدّلة.
المزامنة التي ستحذف أكثر من 1,000 مستند وعُشر المصدر تنتظر 24 ساعة حتى تؤكدها مزامنة ثانية.

المستندات

كل ملف مستند واحد، له معرّف ومواضع الرفع، إضافةً إلى source_url (gs://bucket/name) وbucket وobject وgeneration في بياناته الوصفية.

{ "source_url": "gs://acme-reports/2024/prices.csv" }

يسرد GET /sources/:id/documents ملفاته.

الإخفاقات

GET /sources/:id/failures

curl

curl https://api.conare.ai/sources/src_b805954930e968fe8d4a89f6/failures \
  -H "Authorization: Bearer $CONARE_API_KEY"

Response

{
  "data": [
    {
      "external_id": "gs://acme-reports/2024/minutes.pdf",
      "key": "minutes.pdf-69578779b32368c6",
      "version": "md5:0HKRGpcwGcvjCA5k1+5AFA==;type=pdf",
      "code": "type_mismatch",
      "message": "type_mismatch: the file is not the type declared: declared pdf, but the bytes are text",
      "run_id": "run_1a20d9cdd1b2092406b048ae",
      "attempts": 1,
      "failed_at": "2026-10-21T21:55:33.56975Z"
    }
  ],
  "next_cursor": null
}

الخيار	النوع	الوظيفة
`limit`	integer، الافتراضي 1000	الإخفاقات في كل صفحة، حتى 1,000
`cursor`	string	`next_cursor` الخاص بالصفحة السابقة، `null` في الصفحة الأخيرة

`code`	المعنى
`unsupported_file`	لا يقرأ Conare نوع الملف
`too_large`	أكبر من 512 MiB
`pages_unread`	تعذّر على OCR قراءة الصفحات التي تذكرها الرسالة؛ والباقي قابل للبحث
أخرى	خطأ التحليل، مثل `type_mismatch` أو `unreadable_file`

لا يوقف أي إخفاق المزامنة.
الملف الذي فشل نهائيًا لا يُقرأ مجددًا إلا عند تغيّره.
الملف الذي فشل لسبب عابر يُعاد تجربته في المزامنات الثلاث التالية، ثم يوميًا.

المخطط الكامل: سرد الكائنات التي تعذّر على المصدر حفظها.

الأخطاء

الخطأ	متى
`422 gcs_access_denied`	لا يستطيع الحساب سرد الحاوية؛ تذكر الرسالة الحساب والدور
`422 gcs_not_verified`	لا تحتوي الحاوية على `.conare/<organization id>`؛ تذكر الرسالة الكائن
`422 gcs_bucket_not_found`	لا توجد حاوية بهذا الاسم
`503 gcs_auth_failed`، `503 gcs_unavailable`	تعذّر الوصول إلى Google Cloud Storage؛ أعد المحاولة بعد `Retry-After`

البدء

الأساسيات

الملفات

المزامنة

النماذج

الأدوات

Google Cloud Storage

الحساب

معاينة حاوية

ربط حاوية

المزامنة وفك الربط

المستندات

الإخفاقات

الأخطاء

​الحساب

​معاينة حاوية

​ربط حاوية

​المزامنة وفك الربط

​المستندات

​الإخفاقات

​الأخطاء

الحساب

معاينة حاوية

ربط حاوية

المزامنة وفك الربط

المستندات

الإخفاقات

الأخطاء