نظرة عامة على GraphQL API

يستخدم كل مشروع في Archie Core نقطة نهاية API موحدة. تتعامل نقطة النهاية الواحدة هذه مع استعلامات GraphQL والتحولات والاشتراكات لكل جدول بيانات. يأتي API مُكوّنًا مسبقًا مع التصفية والتقسيم والبحث النصي الكامل وميزات متقدمة أخرى.

يتم إرسال جميع طلبات API إلى عنوان URL التالي:

https://archie-core.services.archie.com/graphql

لتوجيه الطلب إلى مشروعك المحدد، يجب تضمين رأس x-project-id الذي يحتوي على معرف مشروعك في كل طلب HTTP.

فهم الحقول

GraphQL هو مواصفة لطلب الحقول على الكائنات. إليك استعلام Archie Core بسيط يبحث عن مدينة معينة بواسطة id الفريد الخاص بها، ويطلب إرجاع حقلي nameCity و state.

query MyQuery {
  citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
    state
  }
}

وإليك النتيجة:

{
  "data": {
    "citiesById": {
      "id": "e14638cb-6d72-4a36-b30f-9b763136a7bb",
      "nameCity": "Chicago",
      "state": "Illinois"
    }
  }
}

النتيجة لها نفس شكل الاستعلام. هذا هو مفتاح GraphQL: تحصل دائمًا على ما تطلبه، ويعرف الخادم الحقول التي يطلبها العميل.

استعلامات Archie Core GraphQL تفاعلية وتدعم الاستعلامات العلائقية بشكل أصلي. هذا يعني شيئين مهمين:

1. يمكن تغيير الاستعلام في أي وقت.
2. يمكن ربط البيانات ذات الصلة دون كتابة استعلامات قاعدة بيانات معقدة ومُسلسلات.

فهم المعاملات

تزداد قوة Archie Core GraphQL API بالقدرة على تحديد معاملات مختلفة عند تنفيذ استعلام. تم توضيح ذلك في المثال أعلاه، حيث يتم تمرير سلسلة UUID محددة كمعامل للاستعلام (...citiesById(id: "e14638cb...")).

عند إنشاء جداول البيانات في Data Builder، يمكن استخدام أي حقل مُحدد على أنه فريد كمعامل للاستعلام.

على سبيل المثال، نظرًا لأن جدول Cities يحتوي على حقل ID مُعيّن كفريد (كونه المفتاح الأساسي)، يمكننا بعد ذلك الاستعلام عن سجل City محدد:

query MyQuery {
  citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
    state
  }
}

المتغيرات

يمكنك جعل الاستعلامات قابلة لإعادة الاستخدام وديناميكية باستخدام المتغيرات في API Explorer.

للعمل مع المتغيرات، تحتاج إلى:

1. استبدال القيمة الثابتة في الاستعلام بـ $variableName.
2. التصريح عن $variableName كأحد المتغيرات المقبولة من الاستعلام.
3. تمرير variableName: value في قاموس المتغيرات المنفصل.

إليك الاستعلام:

query MyQuery ($filter: StudentsFilter) {
  students(filter: $filter) {
    items {
      firstName
      email
    }
  }
}

إليك المتغير:

{
  "filter": {
    "isActive": {
      "equals": true
    }
  }
}

وهذه هي النتيجة:

{
  "data": {
    "students": {
      "items": [
        {
          "firstName": "James",
          "email": "james.smith@example.com"
        },
        {
          "firstName": "John",
          "email": "john.williams@example.com"
        },
        {
          "firstName": "Mary",
          "email": "mary.brown@example.com"
        },
        {
          "firstName": "Mary",
          "email": "mary.johnson@example.com"
        },
        {
          "firstName": "Elizabeth",
          "email": "elizabeth.davis@example.com"
        }
      ]
    }
  }
}

الأسماء المستعارة

تُستخدم الأسماء المستعارة لإرجاع كائنات بأسماء مختلفة عن أسماء حقولها. هذا مطلوب عند جلب نفس نوع الكائنات بمعاملات مختلفة في استعلام واحد.

أدناه يمكنك رؤية أن المدينة الأولى لها اسم مستعار “cityOne”:

query MyQuery {
  cityOne: citiesById(id: "e14638cb-6d72-4a36-b30f-9b763136a7bb") {
    id
    nameCity
  }

  cityTwo: citiesById(id: "0174dc55-d494-4ebc-a0e9-13575461cad4") {
    id
    nameCity
  }
}

النتيجة:

{
  "data": {
    "cityOne": {
      "id": "e14638cb-6d72-4a36-b30f-9b763136a7bb",
      "nameCity": "Chicago"
    },
    "cityTwo": {
      "id": "0174dc55-d494-4ebc-a0e9-13575461cad4",
      "nameCity": "Miami"
    }
  }
}

الشظايا

يمكن أن تصبح الاستعلامات طويلة ومعقدة. تنشئ الشظايا مجموعة من الحقول التي يمكن استخدامها لتمثيل المجموعة المحددة. إذا أردت عدة حقول من مؤلفين مختلفين، يمكنك استخدام شظية، بدلاً من تكرار الحقول مرتين. في هذا الاستعلام، لدينا شظية تسمى { ...studentFrag }:

query MyQuery {
  studentA: studentsById(id: "287cff0a-345b-4cca-9e9a-75a2161238fd") { ...studentFrag}

  studentB: studentsById(id: "97fb89ac-e0ad-44f5-b671-24a1b751287c") { ...studentFrag}
}

fragment studentFrag on Students {
      id
      firstName
      email
      isActive
      city {
        nameCity
        state
      }
    }

النتيجة:

{
  "data": {
    "studentA": {
      "id": "287cff0a-345b-4cca-9e9a-75a2161238fd",
      "firstName": "James",
      "email": "james.smith@example.com",
      "isActive": true,
      "city": {
        "nameCity": "Chicago",
        "state": "Illinois"
      }
    },
    "studentB": {
      "id": "97fb89ac-e0ad-44f5-b671-24a1b751287c",
      "firstName": "John",
      "email": "john.williams@example.com",
      "isActive": true,
      "city": {
        "nameCity": "Seattle",
        "state": "Washington"
      }