إنشاء اقتراحات نصية

تستفيد واجهة برمجة التطبيقات "اقتراحات النصوص" من أدوات الذكاء الاصطناعي التوليدي في Product Studio API لإنشاء عناوين وأوصاف المنتجات وتحسينها. يمكنك استخدامها لتحسين تفاعل العملاء والإحالات الناجحة، وتبسيط عملية إدارة معلومات المنتجات وتعديلها. يمكن أن تساعدك ميزات Product Studio API في تحسين أداء نشاطك التجاري في مجال البيع بالتجزئة.

ما الذي يمكن إنشاؤه باستخدام واجهة برمجة التطبيقات؟

تساعدك واجهة برمجة التطبيقات "اقتراحات النصوص" في تنفيذ ما يلي:

  • عناوين وأوصاف مقترَحة للمنتجات استنادًا إلى صورة المنتج و/أو سمات المنتج
  • عناوين محسّنة لمحركات البحث لمنتجاتك
  • عناوين منسَّقة بشكل مخصّص لمنتجاتك
  • أوصاف المنتجات من خلاصة المنتجات

يمكنك أيضًا تحديد نبرة الصوت في الأوصاف والحفاظ على الاتساق في جميع بيانات منتجاتك.

البدء السريع

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

تقبل واجهة برمجة التطبيقات ما يلي:

  • سمات المنتج (قاموس JSON): عنصر JSON يحتوي على سمات المنتج (مثل {"title": "White Tee", "brand": "MyBrand", "size": "XL"})
  • صورة المنتج: معرّف URI يشير إلى صورة المنتج (مثل {"uri": "https://my-store.com/img/1.png"})
  • خيارات تنسيق العنوان: مَعلمات لتخصيص عملية إنشاء العناوين، بما في ذلك:
    • attribute_separator: تحدّد الفاصل بين السمات.
    • target_language: تضبط لغة الناتج.
    • attribute_order: تحدّد ترتيب السمات في العنوان الذي تم إنشاؤه.
  • أمثلة على تصنيف البيانات: يمكنك الاطّلاع على مثال حول كيفية إنشاء عنوان من وصف.
  • معرّف سير العمل (output_spec.workflow_id): يحدّد الحقل workflow_id ضمن العنصر output_spec نوع إنشاء النص:
    • title: لإنشاء عنوان المنتج أو تحسينه
    • description: لإنشاء وصف المنتج أو تحسينه
    • tide: لإنشاء عنوان المنتج ووصفه أو تحسينهما

أمثلة

في ما يلي أمثلة على استخدام واجهة برمجة التطبيقات لإنشاء عنوان أو وصف أو كليهما أو تحسينهما من خلال إدخالات مختلفة لبيانات المنتجات. نعرض أيضًا الأخطاء والمشاكل الشائعة وحلولها.

إنشاء عناوين محسَّنة

يوضّح المثال كيفية إنشاء عنوان محسّن.

طلب

يحتوي نص الطلب على معلومات المنتج التي سيتم استخدامها لتحسين العنوان. في ما يلي مثال على بنية الطلب:

POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
   "product_info": {
      "product_attributes": {
         "title": "Nike Mens shoes",
         "description": "Give strength to your step with the Nike Air Zoom Pegasus 38 shoe for Men with shoe size 12. Ensuring the fit is loved by the runners. This shoes comes in Blue color.",
         "brand": "Nike"
      }
   },
   "output_spec": {
      "workflow_id": "title"
   }
}

الردّ

يمكنك توقّع تلقّي ردّ مثل

{
  "title": {
    "text": "Nike Mens shoes Air Zoom Pegasus 38 Running Shoes, Blue, Size 12"
  },
  "metadata": {
    "metadata": {
      "attributes": {
        "color": "Blue",
        "size": "12",
        "product": "Running shoes",
        "model": "Air Zoom Pegasus 38"
      },
    }
  }
}

إنشاء عنوان من صورة فقط

يوضّح المثال كيفية تقديم صورة منتج وإنشاء عنوان محسّن.

طلب

POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
   "product_info": {
      "product_image":{
         "uri": "https://cdn.shopify.com/s/files/1/0653/5879/0892/products/1672082339438_550x825.jpg?v=1672082415"
      }
   },
   "output_spec": {
      "workflow_id": "title",
      "attribute_separator": "-"
   }
}

الردّ

{
  "title": {
    "text": "Rustic Ceramic & Leather Leaves Necklace"
  },
  "metadata": {
    "metadata": {
      "attributes": {
        "material": "Rustic Ceramic & Leather",
        "pattern": "Leaves",
        "product": "Necklace"
      },
    }
  }
}

إنشاء عنوان من وصف

يوضّح المثال كيفية تقديم وصف للمنتج وإنشاء عنوان محسّن.

طلب

POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
   "product_info": {
      "product_attributes": {
         "description": "selling size 12 nike dunks. oh they are red by the way!"
      }
   },
   "output_spec": {
      "workflow_id": "title",
   }
}

الردّ

{
  "title": {
    "text": "Nike Dunks Red Size 12"
  },
  "metadata": {
    "metadata": {
      "attributes": {
        "brand": "Nike",
        "color": "Red",
        "size": "12",
        "product": "Dunks"
      },
    }
  }
}

تحسين العناوين من عنوان ووصف (بالإضافة إلى مثال مخصّص)

في هذا المثال، نصنّف بشكل صريح سمات المنتج التي نريد أن يحدّدها الذكاء الاصطناعي وترتيب السمات في الناتج.

طلب

POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
   "product_info": {
      "product_attributes": {
         "title": "Volumizing & Lengthening Mascara - Dark Brown",
         "description": "This high-impact mascara delivers both voluptuous volume and dramatic length without clumping or smudging.",
         "brand": "Luxe Beauty"
      }
   },
   "output_spec": {
      "workflow_id": "title"
   }
   "title_examples": [
    {
      "product_info": {
        "title": "Lash Paradise Volumizing & Lengthening Mascara - Waterproof - Blackest Black",
        "colour": "Black"
      },
      "title_format": "product",
      "category": "mascara",
      "final_product_info": {
        "product": "Mascara",
        "brand": "Lash Paradise",
        "mascara_type": "Volumizing & Lengthening",
        "colour": "Blackest Black",
        "waterproof": "Waterproof",
      }
    },
    {
      "product_info": {
        "title": "Hypnose Drama Instant Full Body Volume Mascara - Black",
        "colour": "Black"
      },
      "title_format": "product",
      "category": "mascara",
      "final_product_info": {
        "product": "Mascara",
        "brand": "Hypnose",
        "sub_brand": "Drama",
        "mascara_type": "Full Body Volume",
        "colour": "Black",
        "eye_lash_type": "All lash types"
      }
    }
  ]
}

الردّ

{
  "title": {
    "text": "Luxe Beauty Dark Brown Volumizing & Lengthening Mascara"
  },
  "metadata": {
    "metadata": {
      "attributes": {
        "brand": "Luxe Beauty",
        "colour": "Dark Brown",
        "mascara_type": "Volumizing & Lengthening",
        "product": "Mascara"
      },
    }
  }
}

إنشاء وصف من عنوان

يوضّح المثال كيفية تقديم عنوان منتج وطلب أن تنشئ واجهة برمجة التطبيقات وصفًا مطابقًا للمنتج.

طلب

POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
   "product_info": {
      "product_attributes": {
         "title": "Rustic Ceramic & Leather Leaves Necklace",
      }
   },
   "output_spec": {
      "workflow_id": "description"
   }
}

الردّ

{
  "description": {
    "text": "Rustic Ceramic & Leather Leaves Necklace is a beautiful necklace made from high-quality ceramic and leather. It features a unique design that is sure to turn heads.
"
  },
}

إنشاء عنوان ووصف من سمات المنتج (مثل العلامة التجارية واللون)

يوضّح هذا المثال كيفية تقديم سمات المنتج لإنشاء عنوان ووصف مثاليَين للمنتج.

طلب

POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
   "product_info": {
      "product_attributes": {
         "brand": "Mr. Beast",
         "color": "purple",
      },
      "product_image":{
         "uri": "https://mrbeast.store/cdn/shop/files/0015dlv_0000_327.jpg?v=1702754475&width=500"
       }
   },
   "output_spec": {
      "workflow_id": "description"
   }
}

الردّ

{
  "title": {
    "text": "Pajamas - Mr. Beast | Purple"
  },
  "description": {
    "text": "Slip into the ultimate comfort and style with these Mr. Beast pajamas in a vibrant shade of purple. Crafted from the softest materials, these pajamas will envelop you in a cozy embrace, ensuring a restful night's sleep. The shorts feature a relaxed fit, allowing for easy movement, while the top boasts a classic design with a comfortable neckline. Whether you're lounging at home or drifting off to dreamland, these Mr. Beast pajamas are the perfect choice for a peaceful and stylish slumber."
  },
}

اللغات الهدف المتاحة

يحدّد هذا الحقل لغة نص الوصف الذي يتم إنشاؤه في ردّ واجهة برمجة التطبيقات. يمكنك إضافة target_language كجزء من معلَمات output_spec:

{
    "output_spec": {
        "target_language": "language"
    }
}

أمثلة على القيم:

"korean" (Korean)
"english" (English)
"spanish" (Spanish)
"french" (French)

مثال على الطلب

POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
   "product_info": {
      "product_attributes": {
         "title": "Granos de café negro",
         "description": "Los granos de café negro en California",
         "brand": "Parfums de Paris",
         "scent": "Floral",
      },
      "product_image":{
         "uri": "https://mrbeast.store/cdn/shop/files/0015dlv_0000_327.jpg?v=1702754475&width=500"
       }
   },
   "output_spec": {
      "workflow_id": "description",
      "target_language": "japanese",
      "attribute_order": ["scent", "product"],
      "tone": "playful",
   }
}

الردّ

{
  "description": {
    "text": "カリフォルニアの黒いコーヒー豆は、あなたの鼻をくすぐる、甘く、フローラルな香りです。この香りは、コーヒー豆の豊かな香りと、ジャスミンとバラの繊細な花の香りをブレンドしたものです。カリフォルニアの黒いコーヒー豆は、あなたの家を居心地の良いカフェに変え、あなたをリラックスした気分にさせてくれるでしょう。この香りは、コーヒー好きにも、フローラルな香り好きにも最適です。カリフォルニアの黒いコーヒー豆で、あなたの家を幸せな香りで満たしましょう!."
  },
}

تخصيص أسلوب الكتابة لإنشاء الأوصاف

للمساعدة في تأسيس علامتك التجارية وتمييز متجرك على الإنترنت عن المتاجر الأخرى، يمكنك تخصيص أسلوب كتابة الأوصاف التي يتم إنشاؤها. تقدّم واجهة برمجة التطبيقات Text خيارَين:

  • اختيار النبرة المحدّدة مسبقًا: يمكنك الاختيار من قائمة نبرات لإنشاء أوصاف جديدة. تتضمّن القائمة أنماط النبرة التالية:
    • الخط التلقائي: خط بسيط وواضح وأنيق.
    • أسلوب مرح: أسلوب خفيف الظل يستخدم لغة إيجابية وروح الدعابة (نِكات، تورية)، والمبالغة (بدون مفارقة أو سخرية أو إيموجي).
    • الأسلوب الرسمي: اللغة الإنجليزية المعيارية، والقواعد النحوية السليمة، والجمل الكاملة، وعدم استخدام أي لغة عامية أو اختصارات
    • مقنع: منطقي وموجز ومستند إلى الحجج لإقناع القارئ.
    • أسلوب المحادثة: أسلوب ودود وسهل الفهم ومناسب للاستخدام اليومي
  • نبرة صوت خاصة بالعلامة التجارية: يمكنك تقديم أوصاف حالية أو مواد عرض نصية أخرى بنبرة صوت علامتك التجارية. سيحلّل نموذج الذكاء الاصطناعي التوليدي نبرة النص وينشئ "وصفًا لأسلوب الكتابة" وفقًا للجوانب التالية:
    • مستوى اللغة الرسمية (مثل رسمية أو غير رسمية)
    • الإسهاب (مثل، موجز، مسهب جدًا)
    • الأسلوب (مثل احترافي أو إخباري أو إيجابي أو إقناعي)
    • بنية الجملة (مثل "جملة بسيطة تتضمّن أدوات عطف قليلة")
    • الكلمات والعبارات الأكثر استخدامًا

مكتبات العملاء

ننصحك باستخدام مكتبات البرامج للعملاء لإرسال طلباتك. سنشارك معك مكتبات البرامج التي يمكنك تثبيتها في مشروع Maven.

عيّنات تعليمات برمجية

اختَر طريقة المصادقة، واضبط نماذج الرموز هذه باستخدام هذه التعليمات. في ما يلي نموذج يمكنك استخدامه لإنشاء اقتراحات نصية.

Java

import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.shopping.merchant.productstudio.v1alpha.GenerateProductTextSuggestionsRequest;
import com.google.shopping.merchant.productstudio.v1alpha.GenerateProductTextSuggestionsResponse;
import com.google.shopping.merchant.productstudio.v1alpha.OutputSpec;
import com.google.shopping.merchant.productstudio.v1alpha.ProductInfo;
import com.google.shopping.merchant.productstudio.v1alpha.TextSuggestionsServiceClient;
import com.google.shopping.merchant.productstudio.v1alpha.TextSuggestionsServiceSettings;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;

/** This class demonstrates how to generate product text suggestions. */
public class GenerateProductTextSuggestionsSample {

  private static String getName(String accountId) {
    return String.format("accounts/%s", accountId);
  }

  public static void generateProductTextSuggestions(Config config) throws Exception {
    // Obtains OAuth token based on the user's configuration.
    GoogleCredentials credential = new Authenticator().authenticate();

    TextSuggestionsServiceSettings textSuggestionsServiceSettings =
        TextSuggestionsServiceSettings.newBuilder()
            .setCredentialsProvider(FixedCredentialsProvider.create(credential))
            .build();

    String name = getName(config.getAccountId().toString());

    // Calls the API and catches and prints any network failures/errors.
    try (TextSuggestionsServiceClient textSuggestionsServiceClient =
        TextSuggestionsServiceClient.create(textSuggestionsServiceSettings)) {

      ProductInfo productInfo =
          ProductInfo.newBuilder()
              .putProductAttributes("title", "Mens shirt")
              .putProductAttributes("description", "A blue shirt for men in size S")
              .build();

      OutputSpec outputSpec = OutputSpec.newBuilder().setWorkflowId("title").build();

      GenerateProductTextSuggestionsRequest request =
          GenerateProductTextSuggestionsRequest.newBuilder()
              .setName(name)
              .setProductInfo(productInfo)
              .setOutputSpec(outputSpec)
              .build();

      System.out.println("Sending GenerateProductTextSuggestions request: " + name);
      GenerateProductTextSuggestionsResponse response =
          textSuggestionsServiceClient.generateProductTextSuggestions(request);
      System.out.println("Generated product text suggestions response below:");
      System.out.println(response);
    } catch (Exception e) {
      System.out.println("An error has occured: ");
      System.out.println(e);
    }
  }

  public static void main(String[] args) throws Exception {
    Config config = Config.load();
    generateProductTextSuggestions(config);
  }
}

الأخطاء والمشاكل الشائعة

في ما يلي بعض المشاكل الشائعة وحلولها.

يجب توفير معلومات المنتج لإنشاء اقتراحات نصية

في حال تلقّي رسالة الخطأ التالية

Error message:
"error": {
    "code": 400,
    "message": "[product_info] Product info is required to generate text suggestions.",
    "status": "INVALID_ARGUMENT",
 ...
}

أضِف product_info في نص الطلب واملأ بشكل صحيح سمة واحدة على الأقل من product_attributes أو product_image.

على سبيل المثال، سيؤدي نشر هذا المحتوى إلى حدوث خطأ.

POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
   "output_spec": {
      "workflow_id": "title"
   }
}

يجب ملء حقل واحد على الأقل من حقول product_info لإنشاء اقتراحات نصية

هذا الخطأ

{
  "error": {
    "code": 400,
    "message": "[product_info.product_attributes] At least one field of product_info is required to generate text suggestions.",
    "status": "INVALID_ARGUMENT",
 ...
}

يشير إلى أنّه عليك تضمين حقل product_info واحد على الأقل في نص الطلب.

على سبيل المثال، سيؤدي نشر هذا المحتوى إلى حدوث خطأ.

POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
   "product_info": {
   },
   "output_spec": {
      "workflow_id": "title"
   }
}

استخدِم بدلاً من ذلك عبارة مثل

   "product_info": {
        "product_attributes": {
         "description": "Selling size 12 Nike dunks. Oh they are red by the way!"
      }
   }

أو

"product_info": {
    "product_image":{
        "uri": "https://cdn.shopify.com/s/files/1/0653/5879/0892/products/1672082339438_550x825.jpg?v=1672082415"
    }
}

يجب إدخال (شيء) في كل title_example

أخطاء مثل الأمثلة الأربعة التالية

{
  "error": {
    "code": 400,
    "message": "[title_examples.product_info] At least one field of product_info is required in each title_example.",
    "status": "INVALID_ARGUMENT",
 ...
}

أو

{
  ...
    "message": "[title_examples.category] Category is required in each title_example.",
  ...
}

أو

{
  ...
    "message": "[title_examples.title_format] Title format is required in each title_example.",
  ...
}

أو

{
  ...
    "message": "[title_examples.final_product_info] At least one field of final_product_info is required in each title_example.",
  ...
}

تشير إلى أنّك لم تملأ حقلًا فرعيًا مطلوبًا.

على سبيل المثال، سيؤدي الطلب التالي إلى حدوث خطأ.

POST
https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
    "product_info": {
        "product_attributes": {
            "description": "selling size 12 nike dunks. oh they are red by the way!"
        }
    },
    "output_spec": {
        "workflow_id": "title"
    },
    "title_examples": []
}

لحلّ هذه المشكلة، يجب ملء جميع الحقول الفرعية التالية لكل title_example محدّد في الطلب:

  • product_info
  • category
  • title_format
  • final_product_info

في ما يلي مثال على ذلك:

{
   "product_info": {
      "product_attributes": {
         "title": "Volumizing & Lengthening Mascara - Dark Brown",
         "description": "This high-impact mascara delivers both voluptuous volume and dramatic length without clumping or smudging.",
      }
   },
   "output_spec": {
      "workflow_id": "title"
   },
   "title_examples": [
    {
      "product_info": {
        "title": "Lash Paradise Volumizing & Lengthening Mascara - Waterproof - Blackest Black",
        "colour": "Black"
      },
      "title_format": "product",
      "category": "mascara",
      "final_product_info": {
        "product": "Mascara",
        "brand": "Lash Paradise",
        "mascara_type": "Volumizing & Lengthening",
        "colour": "Blackest Black",
        "waterproof": "Waterproof",
      }
    }
  ]
}

Unsupported workflow_id

هذا النوع من الأخطاء

{
  "error": {
    "code": 400,
    "message": "[\u003ceye3 title='/ProductStudioTextGenerationService.GenerateProductText, INVALID_ARGUMENT'/\u003e APPLICATION_ERROR; ... ;Unsupported workflow_id: attributes. Supported workflows are: [\"title\", \"description\", \"tide\"];AppErrorCode=3;StartTimeMs=1740696804045;unknown;ResFormat=uncompressed;ServerTimeSec=0.005976589;LogBytes=256;Non-FailFast;EffSecLevel=none;ReqFormat=uncompressed;ReqID=4d1786f59faa3ea7;GlobalID=0;Server=[2002:a05:6e16:618:b0:2c2:7cfc:bebd]:14001] Invalid value",
    "status": "INVALID_ARGUMENT",
 ...
}

سينتج عن طلب مثل

POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
   "product_info": {
      "product_attributes": {
         "title": "Volumizing & Lengthening Mascara - Dark Brown",
         "description": "This high-impact mascara delivers both voluptuous volume and dramatic length without clumping or smudging.",
   },
   "output_spec": {
      "workflow_id": "attributes"
   }
}

يضبط الطلب workflow_id على "السمات"، ولكن هذا الحقل لا يتيح سوى إحدى القيم التالية:

  • title: لإنشاء عنوان المنتج أو تحسينه
  • الوصف: لإنشاء وصف المنتج أو تحسينه
  • tide: لإنشاء أو تحسين عنوان المنتج ووصفه

نغمة غير متوافقة

يظهر الخطأ "نغمة غير متوافقة"، مثل

{
  "error": {
    "code": 400,
    "message": "[\u003ceye3 title='/ProductStudioTextGenerationService.GenerateProductText, INVALID_ARGUMENT'/\u003e APPLICATION_ERROR; ... ; Unsupported tone: 'asdf'. Supported tones are: [\"default\", \"playful\", \"formal\", \"persuasive\", \"conversational\"];AppErrorCode=3;StartTimeMs=1740697325058;unknown;ResFormat=uncompressed;ServerTimeSec=7.45346E-4;LogBytes=256;Non-FailFast;EffSecLevel=none;ReqFormat=uncompressed;ReqID=f7d9bbbc73a1d342;GlobalID=0;Server=[2002:a05:6918:3486:b0:2bc:ccd4:79e6]:14001] Invalid value",
    "status": "INVALID_ARGUMENT",
 ...
}

سينتج عن طلب مثل

POST https://merchantapi.googleapis.com/productstudio/v1alpha/accounts/{ACCOUNT_ID}:generateProductTextSuggestions

{
   "product_info": {
      "product_attributes": {
         "title": "Volumizing & Lengthening Mascara - Dark Brown",
         "description": "This high-impact mascara delivers both voluptuous volume and dramatic length without clumping or smudging.",
   },
   "output_spec": {
      "workflow_id": "description"
      "tone": "cheerful"
   }
}

لاحظ أنّه تم ضبط tone على "مبهج"، ولكن هذا الحقل لا يتيح سوى إحدى القيم التالية:

  • default: تصميم بسيط وواضح وأنيق
  • أسلوب مرح: أسلوب خفيف الظل يستخدم لغة إيجابية ودعابة (نكات، تورية) ومبالغة (بدون مفارقة أو سخرية أو رموز إيموجي).
  • رسمي: اللغة الإنجليزية المعيارية، وقواعد نحوية سليمة، وجُمل كاملة، وبدون لغة عامية أو اختصارات
  • مقنع: منطقي وموجز ومستند إلى الحجج لإقناع القارئ.
  • أسلوب محادثة: أسلوب ودود وسهل الفهم ومناسب للاستخدام اليومي