الأدوات على هيئة عمليات

ما هي¶

تستطيع واجهة GIS للمؤسسات أن تصف أدواتها ببنية OGC API – Processes (الجزء الأول: الأساس): قائمة بالعمليات، ولكل عملية مدخلاتها ومخرجاتها بصيغة JSON Schema. فالبرمجيات التي تتعامل مع هذا المعيار — محرك سير عمل، أو إضافة لبرنامج GIS مكتبي، أو طبقة تكامل — تستطيع أن تكتشف ما يقدمه Hyz وما تأخذه كل أداة دون تعلّم صيغة فهرس Hyz الخاصة.

يُولَّد هذا الوصف من تعريفات الأدوات نفسها التي تُولَّد منها لوحات البوابة ومرجع الأدوات وHyz MCP، فهو يطابق دائمًا ما تقبله الأدوات فعلًا.

ما ليست عليه¶

لا يدّعي Hyz المطابقة لمعيار OGC API – Processes. هذا وصف بشكل المعيار لغرض الاكتشاف. وثلاثة أمور تختلف عن المعيار، وتذكرها كل عملية:

المعيار	Hyz
تُنفَّذ العملية على ‎/processes/{id}/execution بمستند JSON	تُنفَّذ العملية على مسارها الخاص بصيغة multipart form data — فالملفات تُرسل ملفات. ورابط execute يعطي العنوان ونوع المحتوى
صفحة رئيسية وإعلان ‎/conformance	لا يُقدَّم أي منهما
حالة المهمة على ‎/jobs/{id} بمستند الحالة المعياري	حالة المهمة مستند Hyz الخاص على ‎/jobs/{jobId}

استخدمه لمعرفة الموجود وكيفية استدعائه، واستدعِ الأدوات كما يصفها مرجع الأدوات.

قائمة العمليات¶

GET /api/enterprise/v1/gis/processes

المصادقة كأي استدعاء لواجهة GIS للمؤسسات، بمفتاح تطبيق من مركز التحكم. وتعيد الأدوات التي يحق لذلك المفتاح تشغيلها. والجسم هو المستند نفسه لا مغلّف Hyz.

{
  "processes": [
    {
      "id": "buffer-generator",
      "title": "مولّد النطاق العازل",
      "version": "2026.10.2",
      "jobControlOptions": ["sync-execute", "async-execute"],
      "outputTransmission": ["value"],
      "haiyz": {
        "conformance": "not claimed: a description in the structure of OGC API – Processes",
        "execution": "multipart/form-data",
        "limited": true
      },
      "links": [
        { "rel": "self", "href": "/api/enterprise/v1/gis/processes/buffer-generator" },
        { "rel": "http://www.opengis.net/def/rel/ogc/1.0/execute", "type": "multipart/form-data", "href": "/api/enterprise/v1/gis/buffer" }
      ]
    }
  ]
}

• id هو المعرّف الدائم للأداة. الأسماء القديمة للأداة تبقى تعمل مساراتٍ ولا تُدرج، وتذكرها الأداة في haiyz.aliases.
• version هي نسخة سلوك الأداة. ويسجّلها كل تشغيل محفوظ، فتستطيع لاحقًا أن تحدد أي نسخة أنتجت ملفًا.
• jobControlOptions تتضمن async-execute للأداة التي يمكن تشغيلها مهمةً كذلك.
• haiyz.limited تبيّن هل يُحتسب التشغيل من رصيد أدوات المؤسسة.
• أضف ‎?lang=ar للعناوين والأوصاف بالعربية.

عملية واحدة¶

GET /api/enterprise/v1/gis/processes/{id}

تضيف inputs وoutputs:

{
  "id": "buffer-generator",
  "inputs": {
    "file": { "minOccurs": 1, "maxOccurs": 1, "schema": { "oneOf": [{ "type": "string", "contentEncoding": "binary", "contentMediaType": "application/geo+json" }] } },
    "distance_m": {
      "minOccurs": 0,
      "maxOccurs": 1,
      "schema": { "type": "number", "minimum": -100000, "maximum": 100000, "default": 100, "x-haiyz-unitInput": "unit", "x-haiyz-boundsUnit": "m" },
      "x-haiyz-usedWhen": { "field": "distance_by", "equals": "value" }
    },
    "unit": { "schema": { "type": "string", "enum": ["m", "km", "ft", "mi"], "default": "m" } }
  },
  "outputs": { "result": { "schema": { "type": "object", "required": ["key"] } } }
}

قراءة المدخل:

• minOccurs وmaxOccurs تبيّنان هل هو مطلوب وكم مرة يُرسل — فالدمج يأخذ مدخل files من مرتين إلى خمس.
• schema تحمل الخيارات (enum) والحدود (minimum وmaximum) والقيمة الافتراضية.
• x-haiyz-usedWhen تميّز مدخلًا لا يُعتد به إلا حين يحمل مدخل آخر قيمة معينة: فالحقل distance_m يُستخدم حين تكون قيمة distance_by هي value.
• x-haiyz-unitInput تميّز المسافة: قيمتها بالوحدة التي يسمّيها ذلك المدخل، وحدودها بالأمتار أيًّا كانت الوحدة.
• x-haiyz-encoding: "json-text" تميّز مدخلًا من نوع المصفوفة — عدة أعمدة أو قائمة إحصاءات — يُرسل نصًّا بصيغة JSON في حقل واحد.
• x-haiyz-columnOf تميّز اسم عمود وتبيّن الملف الذي ينتمي إليه.

المعرّف غير المعروف، أو الأداة التي لا يحق للمفتاح تشغيلها، يجيب بالرمز 404 بمستند الاستثناء المعياري.

التنفيذ¶

أرسل المدخلات حقولًا بصيغة multipart إلى رابط execute الخاص بالعملية:

POST /api/enterprise/v1/gis/buffer
Content-Type: multipart/form-data

file[email protected]
target_format=geojson
distance_m=250

الجواب هو مغلّف Hyz الموصوف في مرجع الواجهة: الحقل data.key هو الناتج المخزَّن، وتُنزَّل مخرجات التشغيل من ‎/runs/{runId}/artifacts/{artifactId}. والطلب الذي ترفضه قواعد الأداة يجيب بالرمز 422 مع اسم الحقل والقاعدة.