تعيينات JSON

عند استخدام واجهة برمجة التطبيقات REST في Google Ads API، تكون بصدد استخدام تمثيلات JSON للموارد والأنواع نفسها المحدّدة في ملفات .proto descriptor في Google Ads API. يتّبع مخطّط ترميز JSON مخطّط الترميز الرسمي الموضّح في القسم تعيين JSON من دليل لغة ملفّات التخزين المؤقت للبروتوكول.

بوجه عام، جميع الرسائل من المستوى الأعلى المُرسَلة إلى الخدمات والمُرسَلة منها هي كائنات JSON فردية. تحتوي معظم طلبات التعديل على صفيف operations يحتوي في حدّ ذاته على العديد من عمليات create أو update أو delete. وبالمثل، search الاستجابات هي كائنات JSON تحتوي على مصفوفة results تتضمّن مجموعة نتائج طلب البحث.

يتم تحويل المعرّفات من snake_case (في بروتوكول الحِزم) إلى lowerCamelCase في تنسيق JSON. هناك استثناء ملحوظ لهذه القاعدة عند استخدام search أو searchStream لإرسال طلبات بحث لغة طلب البحث في "إعلانات Google". تستخدم لغة طلب البحث نفسها تنسيق snake case، بغض النظر عن الواجهة التي تستخدمها. ومع ذلك، يتم عرض نتائج طلب البحث في REST على هيئة عناصر JSON عادية وتتضمّن معرّفاتها تنسيق lowerCamelCase.

على سبيل المثال، يستخدم طلب بحث لجلب قائمة بالكلمات الرئيسية النشطة في حساب طريقة الكتابة بأسلوب Snake داخل طلب البحث نفسه (ad_group_criterion وليس adGroupCriterion):

POST /v19/customers/CUSTOMER_ID/googleAds:searchStream HTTP/1.1
Host: googleads.googleapis.com
Content-Type: application/json
Authorization: Bearer ACCESS_TOKEN
developer-token: DEVELOPER_TOKEN

{
  "query": "SELECT ad_group_criterion.keyword.text
            FROM ad_group_criterion
            WHERE ad_group_criterion.type = 'KEYWORD'
            AND ad_group_criterion.status = 'ENABLED'"
}

ومع ذلك، فإنّ الاستجابة هي تمثيل JSON للكائنات (ملفوفة في صفيف JSON لأنّ هذا الطلب يستخدم searchStream) وتستخدم معرّف camelCase adGroupCriterion بدلاً من ذلك:

[
  {
    "results": [
      {
        "adGroupCriterion": {
          "resourceName": "customers/1842689525/adGroupCriteria/55771861891~10003060",
          "keyword": {
            "text": "pay per click"
          }
        }
      },
      ...
    ]
  }
]