Magento 2 GraphQL API : دليل المطور الشامل (2026)

POST https://your-store.com/graphql
Content-Type: application/json

{
  products(filter: { sku: { eq: "24-MB01" } }) {
    items {
      sku
      name
      price_range {
        minimum_price {
          regular_price {
            value
            currency
          }
        }
      }
      image {
        url
        label
      }
    }
  }
}

curl -X POST https://your-store.com/graphql \
  -H "Content-Type: application/json" \
  -d '{"query": "{ products(filter: { sku: { eq: \"24-MB01\" } }) { items { sku name } } }"}'

-H "Store: default"
"

بدونه، قد يعيد ماجنتو بيانات من طريقة عرض المتجر الخاطئة — أسعار خاطئة، لغة خاطئة، عملة خاطئة.

---

## المخطط الأساسي: المنتجات والفئات والبحث

**قائمة الفئات مع الفلاتر**

```graphql
{
  categoryList(filters: { url_key: { eq: "gear" } }) {
    id
    name
    products(pageSize: 12, currentPage: 1) {
      total_count
      items {
        sku
        name
        small_image { url }
        price_range {
          minimum_price {
            final_price { value currency }
          }
        }
      }
      page_info {
        current_page
        total_pages
      }
    }
  }
}

{
  products(search: "backpack", pageSize: 10) {
    total_count
    items {
      sku
      name
      url_key
    }
  }
}
"

يعتمد البحث على مفهرس `catalogsearch_fulltext` و Elasticsearch/OpenSearch. إذا أرجع البحث نتائج فارغة، أعد الفهرسة أولاً:

```bash
bin/magento indexer:reindex catalogsearch_fulltext

{
  products(filter: { sku: { eq: "MH01" } }) {
    items {
      sku
      name
      ... on ConfigurableProduct {
        configurable_options {
          attribute_code
          label
          values {
            value_index
            label
          }
        }
        variants {
          product {
            sku
            name
            price_range {
              minimum_price {
                final_price { value }
              }
            }
          }
        }
      }
    }
  }
}

mutation {
  createEmptyCart
}

{ "data": { "createEmptyCart": "abc123xyz" } }

mutation {
  addProductsToCart(
    cartId: "abc123xyz"
    cartItems: [{ sku: "24-MB01", quantity: 1 }]
  ) {
    cart {
      items {
        quantity
        product {
          name
          sku
        }
      }
      prices {
        grand_total {
          value
          currency
        }
      }
    }
  }
}

mutation {
  mergeCarts(
    source_cart_id: "abc123xyz"
    destination_cart_id: "customer-cart-id"
  ) {
    items { quantity product { sku } }
  }
}

mutation {
  setShippingAddressesOnCart(
    input: {
      cart_id: "abc123xyz"
      shipping_addresses: [{
        address: {
          firstname: "John"
          lastname: "Doe"
          street: ["123 Main St"]
          city: "Paris"
          postcode: "75001"
          country_code: FR
          telephone: "0600000000"
        }
      }]
    }
  ) {
    cart {
      shipping_addresses {
        available_shipping_methods {
          carrier_code
          method_code
          amount { value currency }
        }
      }
    }
  }
}

mutation {
  generateCustomerToken(
    email: "[email protected]"
    password: "Password123!"
  ) {
    token
  }
}

-H "Authorization: Bearer <token>"
"

تنتهي صلاحية tokens بناءً على تكوين Admin (`Stores → Configuration → Services → OAuth → Customer Token Lifetime`). القيمة الافتراضية هي ساعة واحدة — خطط لمنطق التحديث في واجهتك الأمامية.

**استعلام introspection (للمطورين فقط)**

عطّل introspection في الإنتاج للأمان. في التطوير، استكشف المخطط:

```graphql
{
  __schema {
    types {
      name
      kind
    }
  }
}

app/code/MagentoMastery/GraphQlDemo/
├── registration.php
├── etc/
│   ├── module.xml
│   └── schema.graphqls
└── Model/
    └── Resolver/
        └── HelloWorld.php

type Query {
    helloWorld(name: String): String
      @resolver(class: "MagentoMastery\\GraphQlDemo\\Model\\Resolver\\HelloWorld")
      @doc(description: "Returns a greeting string")
}

<?php
declare(strict_types=1);

namespace MagentoMastery\GraphQlDemo\Model\Resolver;

use Magento\Framework\GraphQl\Config\Element\Field;
use Magento\Framework\GraphQl\Query\ResolverInterface;
use Magento\Framework\GraphQl\Schema\Type\ResolveInfo;

class HelloWorld implements ResolverInterface
{
    public function resolve(
        Field $field,
        $context,
        ResolveInfo $info,
        ?array $value = null,
        ?array $args = null
    ): string {
        $name = $args['name'] ?? 'World';
        return "Hello, {$name}!";
    }
}

{ helloWorld(name: "Magento") }

bin/magento setup:upgrade
bin/magento cache:flush

type Mutation {
    subscribeNewsletter(email: String!): NewsletterOutput
      @resolver(class: "MagentoMastery\\GraphQlDemo\\Model\\Resolver\\SubscribeNewsletter")
}

type NewsletterOutput {
    success: Boolean!
    message: String
}

<?php
declare(strict_types=1);

namespace MagentoMastery\GraphQlDemo\Model\Resolver;

use Magento\Framework\Exception\LocalizedException;
use Magento\Framework\GraphQl\Config\Element\Field;
use Magento\Framework\GraphQl\Exception\GraphQlInputException;
use Magento\Framework\GraphQl\Query\ResolverInterface;
use Magento\Framework\GraphQl\Schema\Type\ResolveInfo;

class SubscribeNewsletter implements ResolverInterface
{
    public function resolve(
        Field $field,
        $context,
        ResolveInfo $info,
        ?array $value = null,
        ?array $args = null
    ): array {
        $email = $args['email'] ?? '';

        if (!filter_var($email, FILTER_VALIDATE_EMAIL)) {
            throw new GraphQlInputException(__('Invalid email address.'));
        }

        // Subscribe logic here...

        return [
            'success' => true,
            'message' => 'Subscribed successfully.',
        ];
    }
}
"

ارمِ `GraphQlInputException` لأخطاء العميل (مستوى 400) و `GraphQlAuthorizationException` لفشل المصادقة — يقوم ماجنتو بترجمتها إلى استجابات خطأ GraphQL المناسبة.

---

## الأداء والتخزين المؤقت

يمكن أن يكون GraphQL أبطأ من المتوقع إذا طلب العملاء حقولاً متداخلة كثيرة. طبّق هذه القواعد في الإنتاج:

**1. حدد عمق وتعقيد الاستعلام**

استخدم proxy عكسي أو حدود تعقيد الاستعلام المضمنة في ماجنتو (Adobe Commerce) لحظر الاستعلامات المسيئة.

**2. خزن مؤقتًا في CDN للاستعلامات المجهولة**

خزن مؤقتًا فقط الاستعلامات التي لا تتضمن tokens عميل أو معرفات سلة. استعلامات قائمة المنتجات مرشحة جيدة لـ CDN عند مفتاحها بواسطة المتجر + تجزئة الاستعلام.

**3. تجنب N+1 في المحللات المخصصة**

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

**4. اطلب فقط ما تعرضه**

```graphql
items { sku name description { html } }

items { sku name small_image { url } price_range { minimum_price { final_price { value } } } }