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

> ## Agent Instructions
> Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`.
> The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown.
> Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1.
> Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples.
> Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt.

# Google Cloud Storage

> اجعل الملفات في حاوية Google Cloud Storage قابلة للبحث في مساحة أسماء.

يحفظ مصدر Google Cloud Storage حاويةً، أو بادئات منها، في مساحة أسماء واحدة. يُقرأ كل ملف كما يُقرأ [الرفع](https://docs.conare.ai/ar/files.md)، والملف المحذوف من الحاوية يفقد مستنداته.

**1. منح الوصول**

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

```bash gcloud theme={null}
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
```

**2. معاينة الحاوية**

```bash curl theme={null}
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/"]}'
```

**3. ربطها**

```bash curl theme={null}
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`

```json Response theme={null}
{
  "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` الكائن المطلوب إنشاؤه.

المخطط الكامل: [الحساب الذي تُمنح له الحاوية](https://docs.conare.ai/ar/api-reference/sources/get-the-bucket-service-account.md).

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

`POST /sources/gcs/preview`

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

```json Response theme={null}
{
  "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 ثوانٍ |

المخطط الكامل: [معاينة حاوية](https://docs.conare.ai/ar/api-reference/sources/preview-a-bucket.md).

## ربط حاوية

أرسل `"type": "gcs"` إلى [`POST /sources`](https://docs.conare.ai/ar/sources#ربط-مصدر)؛ تبدأ المزامنة الأولى فورًا، ويمكن لمفتاح مقيّد بمساحة الأسماء ربطها.

```json Response theme={null}
{
  "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 ساعة حتى تؤكدها مزامنة ثانية.

## المستندات

كل ملف مستند واحد، له معرّف ومواضع [الرفع](https://docs.conare.ai/ar/files.md#المستندات-المخزّنة)، إضافةً إلى `source_url` (`gs://bucket/name`) و`bucket` و`object` و`generation` في بياناته الوصفية.

```json theme={null}
{ "source_url": "gs://acme-reports/2024/prices.csv" }
```

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

## الإخفاقات

`GET /sources/:id/failures`

```bash curl theme={null}
curl https://api.conare.ai/sources/src_b805954930e968fe8d4a89f6/failures \
  -H "Authorization: Bearer $CONARE_API_KEY"
```

```json Response theme={null}
{
  "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` |

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

المخطط الكامل: [سرد الكائنات التي تعذّر على المصدر حفظها](https://docs.conare.ai/ar/api-reference/sources/list-a-sources-failures.md).

## الأخطاء

| الخطأ | متى |
| - | - |
| `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` |


## Related topics

- [Get the bucket service account](https://docs.conare.ai/ar/api-reference/sources/get-the-bucket-service-account.md)
- [المصادر](https://docs.conare.ai/ar/sources.md)
- [Preview a bucket](https://docs.conare.ai/ar/api-reference/sources/preview-a-bucket.md)
- [List a source's failures](https://docs.conare.ai/ar/api-reference/sources/list-a-sources-failures.md)
- [Sync a source now](https://docs.conare.ai/ar/api-reference/sources/sync-a-source-now.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.