Shopify: باز کردن قدرت مدل محصول جدید Shopify و API

مقدمه

تغییرات اخیر زیادی در رابطه با مدیریت اطلاعات محصول با API های Shopify وجود داشته است ، به ویژه در نحوه تعامل توسعه دهندگان برنامه با داده های محصول. این موارد شامل تغییر در مدل محصول ، نحوه عملکرد خود محصولات و مهاجرت از استراحت به GraphQL است.

من به عنوان یک توسعه دهنده که تجربه ساخت و ساز با مدل جدید APIS را دارد ، می خواهم تجربیات خود را به اشتراک بگذارم و نمونه های دنیای واقعی را باز کنم که به درک به روزرسانی ها و مهاجرت کمک می کند.

مدل محصول

بیایید ابتدا مدل محصول را تغییر دهیم ، زیرا این به ما کمک می کند تا درک کنیم که چرا GraphQL به روشی که انجام می دهد عمل می کند.

پیش از این ، مدل محصول با محصول ، تصاویر ، انواع محصول و موارد موجودی که همه با هم به هم پیوسته بودند ، جمع و جور بود. این تصاویر به محصولات و انواع گره خورده بودند ، بنابراین نمی توان بین محصولات موجود در هر گالری فایل/رسانه استفاده مجدد کرد.

اطلاعات موجودی موجودی مانند SKU و وزن همه با انواع محصول ترکیب شده اند. و البته ، انواع محصول همیشه به محصولات وصل می شدند به این معنی که ما فقط می توانستیم 200 نوع داشته باشیم.

این کار از منظر توسعه دهنده کار را آسان کرده است ، زیرا همه داده ها را در یک تماس API دریافت کردید ، اما می بینید که چگونه به راحتی قابل توسعه نبوده و یا اثبات آینده ای در آینده نیست.

مدل محصول جدید این مؤلفه های کلیدی یک محصول را به چیزی که شبیه تصویر زیر است ، جدا می کند:

آنچه شما توجه خواهید کرد این است که این همچنین با طرح Admin Shopify یک محصول ، با یک صفحه جداگانه برای انواع محصول و جعبه های جداگانه برای رسانه و موجودی در آن مطابقت دارد. به یاد آوردن طرح محصول Admin Shopify هنگامی که به دنبال API های محصول GraphQL هستیم ، مفید خواهد بود.

تغییرات در مدل قابلیت های بزرگی به ما می دهد:

• تا 2048 نوع.
• رسانه ها را می توان بین محصولات بدون کپی کردن چندین بار به اشتراک گذاشت ، و این باعث می شود که بازرگانان آسانتر شوند
• پشتیبانی از فیلم های بزرگتر و مدل های سه بعدی و همچنین تصاویر.
• تفکیک اطلاعات کالایی و محصول محصول از موجودی و داده های عملیاتی.

می توانید در مورد نحوه استفاده از آخرین API های محصول GraphQL در اسناد توسعه دهنده ، که مدل و مؤلفه ها و برخی از دلایل تغییرات را توصیف می کند ، اطلاعات بیشتری کسب کنید و امیدوارم بتوانید برخی از فرصت هایی را که این بروزرسانی برای ما باز می کند ، به عنوان توسعه دهندگان برای انجام کارهای بیشتری با محصولات مشاهده کنید.

گرافیک

بیایید اکنون به برخی از Graphql شیرجه بزنیم. اگر تازه وارد GraphQL هستید ، توصیه می کنم ابتدا مستندات توسعه دهنده Shopify را بررسی کنید ، که شامل یک راهنمای دقیق مهاجرت نیز می شود.

محدودیت نرخ

یکی از جنبه های مهم برای درک هنگام مهاجرت از استراحت به GraphQL این است که محدودیت نرخ کاملاً متفاوت است. ممکن است شما نیاز به برقراری تماس بیشتر در GraphQL نسبت به استراحت داشته باشید ، اما محدودیت نرخ بر اساس یک سیستم امتیاز محاسبه می شود.

امتیازها یا با توجه به میزان هزینه هر پرس و جو ، یا با جهش هایی که همیشه 10 امتیاز هزینه خواهد داشت ، صرف نظر از تغییرات ایجاد شده تعیین می شود. در مقایسه با محدودیت های استراحت ، امتیاز بیشتری در GraphQL دارید ، بنابراین در صورت نیاز به درخواست های اضافی GraphQL در مقایسه با REST ، بیش از حد نگران نباشید.

همچنین می توانید از عملیات فله در GraphQL برای ایجاد یا به روزرسانی چندین محصول و انواع در یک GO استفاده کنید یا حجم بیشتری از داده ها را پردازش کنید.

ایجاد

اولین کاری که می خواهیم با هر محصول انجام دهیم ایجاد آن است. دقیقاً چگونه این کار را انجام می دهید به نحوه کار شما بستگی دارد.

ابتدا می توانید با استفاده از ProductCreate فقط اطلاعات سطح برتر را ایجاد کنید و اگر از ابتدا شروع می کنید ، این گزینه ساده تر را توصیه می کنم. می توانید نمونه ای از آنچه در زیر به نظر می رسد را ببینید:

const query = `mutation createProduct($product: ProductCreateInput!) {
  productCreate(product: $product) {
    product {
      id
    }
    userErrors {
      field
      message
    }
  }
}`

const variables = {
  "product": {
    "title": "Winter hat",
    "productOptions": [
      {
        "name": "Color",
        "values": [
          { "name": "Grey" },
          { "name": "Black" }
        ]
      }
    ]
  }
}

از طرف دیگر می توانید از ProductSet استفاده کنید که به شما امکان می دهد محصولی کامل تر با انواع و غیره ایجاد کنید ، که در صورت مهاجرت از یک برنامه موجود یا یکپارچه سازی استراحت آسان تر است. با توجه به پیچیدگی موجود در اینجا ، نمونه ای از این مورد را در زیر می آورم ، جایی که ما یک محصول ، انواع و انواع و اطلاعات موجودی را ایجاد می کنیم.

نکته مهمی که در اینجا باید به آن توجه داشت این است که ProductSet یک نقطه پایانی Upsert است ، یک محصول را ایجاد یا به روز می کند ، بنابراین فقط از این امر آگاه باشید ، به خصوص اگر فقط اطلاعات مختلف را به روز می کنید.

اولین چیزی که از مثال برای تماس با ما تماس بگیرید این است که ما یک گزینه ورودی همزمان در اینجا داریم ، اگر شما در حال ایجاد یک محصول بزرگ با تعداد زیادی پرونده و انواع هستید ، بهتر است این کار را انجام دهید نه همزمان در غیر این صورت ممکن است زمان وقوع آن باشد. سپس می توانید از ProductSetOperation پرس و جو کنید تا در زمان تکمیل این کار را بررسی کنید.

مثل همیشه با GraphQL اطمینان حاصل کنید که کاربر را در پاسخ خود بررسی می کنید تا هرگونه مشکل در مورد ورودی خود را بدست آورید. اگر می خواهید محصولات زیادی را به صورت یک طرفه بسازید ، می توانید این کار را به عنوان یک کار فله اجرا کنید.

در ورودی در اینجا مثالی ایجاد شده است که محصولی با یک نوع ، مورد رسانه (پرونده) و اطلاعات موجودی ایجاد می کند.

const query = `
mutation createProductAsynchronous($productSet: ProductSetInput!, $synchronous: Boolean!) {
  productSet(synchronous: $synchronous, input: $productSet) {
    product {
      id
    }
    productSetOperation {
      id
      status
      userErrors {
        code
        field
        message
      }
    }
    userErrors {
      code
      field
      message
    }
  }
}`

const variables = {
  "synchronous": false,
  "productSet": {
    "title": "Winter hat",
    "metafields": [
      {
        "description": "",
        "key": "",
        "namespace": "",
        "type": "",
        "value": ""
      }
    ],
    "productOptions": [
      {
        "name": "Color",
        "position": 1,
        "values": [
          {
            "name": "Grey"
          },
          {
            "name": "Black"
          }
        ]
      }
    ],
    "variants": [
      {
        "optionValues": [
          {
            "optionName": "Color",
            "name": "Grey"
          }
        ],
        "price": 79.99,
        "inventoryItem": {
          "measurement": {
            "weight": {
              "value": 1.70,
              "unit": "GRAMS"
            }
          },
          "sku": "SKU-123",
          "tracked": true,
        }
      },
      {
        "optionValues": [
          {
            "optionName": "Color",
            "name": "Black"
          }
        ],
        "price": 69.99,
        "inventoryItem": {
          "measurement": {
            "weight": {
              "value": 1.70,
              "unit": "GRAMS"
            }
          },
          "sku": "SKU-456",
          "tracked": true,
        }
      }
    ]
  }
}

انواع مختلف

اگر از ProductCreate استفاده کرده اید و می خواهید سپس انواع مختلفی از رسانه ها ایجاد کنید ، می توانید از ProductVarianTsBulkCreate استفاده کنید که به شما امکان می دهد انواع و موارد رسانه ای را روی یک محصول ایجاد کنید.

من شخصاً توصیه می کنم از ProductCreate استفاده کنید و این روش ، به جای ProductSet ، برای مدیریت محصول و انواع مختلف ، زیرا درک همه چیز را کمی ساده تر می کند. داده های ورودی پیچیده کمتری دارند ، خطر کمتری وجود دارد زیرا این نقاط پایانی صعود نیست و شما باید شناسه های کمتری را نسبت به ProductSet ذخیره کنید. من معتقدم که این امر شما را به خوبی برای به روزرسانی ها تنظیم می کند زیرا آنها از یک قالب مشابه پیروی می کنند.

const query = `mutation productVariantsCreate($productId: ID!, $variants: [ProductVariantsBulkInput!]!, $media: [CreateMediaInput!]) {
  productVariantsBulkCreate(productId: $productId, variants: $variants, media: $media) {
    productVariants {
      id
      title
      selectedOptions {
        name
        value
      }
    }
    userErrors {
      field
      message
    }
  }
}`

const variables = {
  "productId": "gid://shopify/Product/20995642",
  "variants": [
    {
      "price": 15.99,
      "compareAtPrice": 19.99,
      "optionValues": [
        {
          "name": "Golden",
          "optionId": "gid://shopify/ProductOption/328272167"
        }
      ]
    }
  ],
  "media": [
    {
      "mediaContentType": "IMAGE",
      "originalSource": "someExternalURL.jpg"
    },
    {
      "mediaContentType": "VIDEO",
      "originalSource": "stagedMediaResourceURL"
    }
  ]
}

به روزرسانی

پس از داشتن محصولی ، می خواهید آن را به روز کنید یا انواع آن را به روز کنید. من به روزرسانی رسانه را در بخش بعدی پوشش می دهم.

باز هم ، می توانید از ProductSet در اینجا استفاده کنید ، زیرا محصول را به روز می کند. اطمینان حاصل کنید که آیا این کار را انجام می دهید ، شناسه هایی را برای انواع موجود ، پرونده ها و غیره ارائه می دهید. در غیر این صورت با نسخه های مختلف یا محتوای محصول دیگر به پایان می رسید.

از طرف دیگر می توانید از روشهای خاص استفاده کنید ، باز هم این همان چیزی است که من توصیه می کنم ، ما ProductUpdate ، ProductVariantsBulkUpdate را دریافت کرده ایم که می تواند به شما امکان دهد به راحتی ویژگی های خاصی را در محصول به روز کنید.

نمونه ای از به روزرسانی یک محصول و اضافه کردن رسانه.

const query = `mutation updateProductData($input: ProductInput!, $media: [CreateMediaInput!]) {
  productUpdate(input: $input, media: $media) {
    product {
      id
    }
    userErrors {
      field
      message
    }
  }
}`

const variables = {
  "input": {
    "id": "gid://shopify/Product/912855135",
    "descriptionHtml": "Updated description"
  },
  "media": [
    {
      "mediaContentType": "IMAGE",
      "originalSource": "someExternalURL.jpg"
    },
    {
      "mediaContentType": "VIDEO",
      "originalSource": "stagedMediaResourceURL"
    }
  ]
}

همچنین اگر به دنبال تغییر گزینه های محصول یا وضعیت منتشر شده به عنوان مثال هستید ، روشهای مشخص دیگری نیز وجود دارد.

نمونه ای از یک محصول موجود با گزینه های رنگی ، اکنون گزینه های اندازه را اضافه می کند و به طور خودکار انواع جدید را ایجاد می کند. اگر محصول در ابتدا ایجاد شده از گزینه های اندازه برخوردار نبود.

const query = `mutation createAdditionalOptions($productId: ID!, $options: [OptionCreateInput!]!, $variantStrategy: ProductOptionCreateVariantStrategy) {
  productOptionsCreate(productId: $productId, options: $options, variantStrategy: $variantStrategy) {
    userErrors {
      field
      message
      code
    }
  }
}`

const variables = {
  "productId": "gid://shopify/Product/20995642",
  "variantStrategy": "CREATE",
  "options": [
    {
      "name": "Size",
      "values": [
        { "name": "Small" },
        { "name": "Medium" },
        { "name": "Large" }
      ]
    }
  ]
}

مدیریت رسانه

مستندات توسعه دهنده به طور جامع نحوه مدیریت رسانه برای یک محصول را توصیف می کند ، بنابراین من آنچه را که در آنجا بیان شده است تکرار نمی کنم ، اما چند مورد وجود دارد که فکر می کنم برای برجسته کردن مهم هستند:

1. پیش از این ، تماس های استراحت فقط یک بار از یک تصویر پشتیبانی می کردند. با استفاده از روش های GraphQL ، می توانید چندین تصویر و رسانه های دیگر را در همان تماس ProductUpdate بارگذاری کنید.
2. همچنین می توانید رسانه های خود را روی صحنه ببرید تا چندین تصویر ، فیلم و مدل های سه بعدی به طور همزمان اضافه شوند و این امر را برای اضافه کردن چندین مورد رسانه به طور همزمان کارآمدتر می کند.
3. اگر می خواهید چندین محصول و رسانه را به روز کنید ، می توانید از واردات فله با ProductUpdate نیز استفاده کنید.
4. اگر چندین رسانه/تصویر را به طور همزمان در یک جهش GraphQL اضافه می کنید ، این تنها 10 امتیاز برای محدودیت نرخ هزینه خواهد داشت.
5. شما هنوز هم می توانید هنگام افزودن آن به یک محصول یا نوع ، یک پیوند خارجی به یک تصویر وارد کنید. با این حال ، این به طور معمول بدان معنی است که شما باید ابتدا آن را در جایی میزبانی کنید. اکنون می توانید از StageUploadsCreate استفاده کنید ، بنابراین دیگر نیازی به انجام این کار ندارید ، و می توانید چندین تصویر/فیلم یا موارد سه بعدی را به صورت یک بار بارگذاری کنید!

مورد موجودی

تاکنون با اطلاعات مربوط به محصول یا محصول ، که بیشتر مربوط به تجارت محصول و آماده سازی آن برای فروش است ، سر و کار داشته ایم. این جایی است که مورد موجودی در حال بازی است ، این نشان دهنده کالای فیزیکی واقعی است که فروخته می شود.

در اینجا جایی است که واحد نگهدارنده سهام (SKU) ، وزن یا سایر اطلاعات لجستیکی وجود دارد و در هر مکان به سطح موجودی مختلف وصل می شود. همانطور که قبلاً بحث کردیم می توانید برخی از این خصوصیات را تنظیم کنید. با این حال ، روش های خاص خود را نیز دارد ، به عنوان مثال به روزرسانی یک مورد موجودی.

نمونه ای از به روزرسانی اطلاعات.

const query = `mutation inventoryItemUpdate($id: ID!, $input: InventoryItemInput!) {
  inventoryItemUpdate(id: $id, input: $input) {
    inventoryItem {
      id
    }
    userErrors {
      field
      message
    }
  }
}`

const variables = {
  "id": "gid://shopify/InventoryItem/43729076",
  "input": {
    "cost": 145.89,
    "tracked": false,
    "countryCodeOfOrigin": "US",
    "provinceCodeOfOrigin": "OR",
    "harmonizedSystemCode": "621710",
    "sku": "SKU-123",
    "measurement": {
      "weight": {
        "value": 1.70,
        "unit": "GRAMS"
      }
    }
  }
}

InventoryItem همچنین دارای شبکه های وب خاص خود است ، بنابراین اگر فقط به این اطلاعات نیاز دارید ، به عنوان مثال برای یک انبار ، می توانید به جای تکیه بر وب سایت های محصول ، در وب سایت موجودی مشترک شوید ، که باید کمی کارآمدتر باشد.

سرفه های وب

اگر هنوز از Webhooks استفاده نمی کنید ، آنها ابزاری مفید برای دریافت اطلاعات از Shopify به صورت غیر همزمان و بدون محدودیت نرخ هستند. اگر می خواهید پس زمینه بیشتر https://shopify.dev/docs/apps/build/webhooks می خواهید ، اسناد مفیدی در اینجا وجود داشته باشد.

Webhooks Product اکنون فقط 100 نوع اول را شامل می شود ، همه انواع اضافی در ویژگی “variant_ids” ذکر می شوند ، این نیز بر روی تمام نسخه های Product Webhook ساخته می شود. این به شما اطلاع می دهد که کدام انواع به روز شده است ، می توانید از شناسه استفاده کنید تا بتوانید اطلاعات مختلف محصول را از Shopify API دریافت کنید.

همچنین ، این فرصت در اینجا وجود دارد که فراتر از شبکه های وب فقط محصول باشد ، زیرا همچنین وب سایت هایی برای به روزرسانی مورد موجودی ، به روزرسانی های سطح موجودی ، انواع موجود در داخل و خارج از سهام وجود دارد. بنابراین ، در صورت وجود جایگزینی که برای شما مفید باشد ، حتماً مستندات را بررسی کنید!

مثال استفاده از مورد

بیایید یک سناریوی کامل دنیای واقعی را باز کنیم. به عنوان مثال ، تصور کنید که شما یک SKU محصولات دارید و می خواهید اطلاعات موجودی و وضعیت انتشار آن را به روز کنید ، که این یک روند مشترک است.

اینگونه است که من به مشکل نزدیک می شوم و تعیین می کنم کدام تماس های GraphQL ممکن است نیاز داشته باشم:

1. این یک SKU است ، بنابراین یک مورد موجودی است که مربوط به یک نوع محصول است (می دانیم که از آنجا که ورودی در مدیر Shopify قرار دارد) ، بنابراین می توانیم آن پرس و جو را پیدا کنیم و ببینیم که آیا می توانیم توسط SKU جستجو کنیم ، که می توانیم https://shopify.docs/api/admin-graphql/2025-01/queries/querians/querians/ https://shopify.dev/docs/api/admin-graphql/2025-01/queries/inventoryitems

2. از هر پرس و جو می توانیم لیستی از انواع محصول را روی گره ها برگردانیم ، بنابراین باید به این موضوع توجه کنیم تا ببینیم چگونه می توانیم به موجودی و انتشار https://shopify.dev/docs/api/admin-graphql/2025-01/objects/productarariant برویم.

3. ما می توانیم در مورد نوع موجودی موجودی را مشاهده کنیم که می گوید برای مدیریت موجودی است ، بنابراین احتمالاً ما به آن شناسه بعداً نیاز خواهیم داشت https://shopify.dev/docs/api/admin-graphql/2025-01/objects/productvariant#-field-inventoryitememem

4. اما هیچ چیز در مورد انتشار وجود ندارد ، به طوری که باید روی محصول نیز باشد ، جایی که نشریات در Admin Shopify قرار دارند ، در مورد انتشار ، تعداد زیادی از زمینه ها در مورد انتشار وجود دارد ، بنابراین شناسه محصول را که احتمالاً به آن احتیاج خواهیم داشت ، به دست می آوریم.

5. از آنجا می دانیم که اکنون به دنبال ایجاد تغییرات موجودی هستیم که این یک جهش و مربوط به یک مورد موجودی خواهد بود. In the inventory section of the GraphQL docs mutations there is inventoryItemUpdate but that does have any quantities on, so let's go with the one that has quantities in the name, which looks right and needs the ID we grabbed earlier https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/inventoryAdjustQuantities

6. ما قبلاً دیدیم که انتشار روی محصول است ، بنابراین به دنبال جهش های محصول برای هر چیزی باشید که به آن مراجعه کنید. انتشار محصول وجود دارد ، که به نظر می رسد درست است و به شناسه محصول از قبل احتیاج دارد ، با این حال مستهجن است ، اما شما را به سمت روش صحیح انتشار چاپ (نام جهش مورد علاقه شخصی من) https://shopify.dev/docs/api/admin-graphql/2025-01/mutations/publishablepublishsublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpublishpubelish)

7. ما باید چندین تماس در اینجا انجام دهیم که خوب است ، یا اگر می خواهید اگر مرتباً آنها را انجام می دهید ، جهش ها را با هم ترکیب کنید. نمونه ای از نحوه انجام این کار در زیر ، اطمینان حاصل کنید که هر جهش دارای نام مستعار منحصر به فرد است. به عنوان مثال من به من زنگ می زنم جدایی وت ضمیمهبشر

const query = `mutation productVariantManageMedia(
  $productId: ID!,
  $detach: [ProductVariantDetachMediaInput!]!,
  $append: [ProductVariantAppendMediaInput!]!) {

  detaching: productVariantDetachMedia(productId: $productId, variantMedia: $variantMedia) {
    userErrors {
      code
      field
      message
    }
  }

  appending: productVariantAppendMedia(productId: $productId, variantMedia: $variantMedia) {
    userErrors {
      code
      field
      message
    }
  }
}`

1. اگر از nodejs استفاده می کنید ، شانس دارید زیرا کتابخانه های Shopify عالی هستند.
   این یک مشتری فوق العاده سبک GraphQL برای آن است @Shopify/Admin-Api-Client
   اگر بین شناسه های REST و IDS GraphQL حرکت می کنید ، همیشه می توانید LegacyResourceId را از API Admin دریافت کنید.

2. در آخر از Shopify CLI و @Shopify/API-CodeGen-PRESET برای تولید انواع نمایش داده های GraphQL خود استفاده کنید که کار با داده ها را بسیار ساده تر می کند.

پایان

من امیدوارم که این امر به اضافه کردن زمینه با نمونه ها و رویکردهای دنیای واقعی برای مقابله با تغییرات اخیر در مدل های محصول و API کمک کرده است. پس از مهاجرت به GraphQL ، برای آینده تنظیم شده اید ، زیرا این فرمت اصلی API Shopify است.

این بدان معناست که ارتقاء و پیگیری هرگونه تغییر باید برای شما و برنامه های شما در آینده ساده تر باشد. امیدوارم بتوانید فرصت هایی را که تغییرات محصول برای ما باز می شود ، برای توسعه برنامه های محصول حتی قدرتمندتر نیز مشاهده کنید.