الأمثلة

يحتوي هذا الدليل على أمثلة حول كيفية طلب نقاط نهاية REST مباشرةً، بدون استخدام مكتبة برامج.

المتطلبات الأساسية

يجب نسخ جميع النماذج المعروضة هنا ولصقها في shell bash باستخدام الأمر curl.

يجب أن يتوفّر لك أيضًا رمز مميز للمطوِّر، ويمكنك استخدام إذن وصول إلى حساب تجريبي، بالإضافة إلى حساب إداري على "إعلانات Google" يتضمّن حساب عميل واحدًا على الأقل.

متغيّرات البيئة

أدخِل بيانات الاعتماد وأرقام التعريف الخاصة بالحساب كما هو موضّح، ثم انسخها والصقها في نافذة الطرفية لضبط متغيّرات البيئة المستخدَمة في الأمثلة اللاحقة. يقدّم دليل التفويض تعليمات حول كيفية إنشاء رمز مميز للوصول إلى OAuth 2.0.

API_VERSION="20"
DEVELOPER_TOKEN="DEVELOPER_TOKEN"
OAUTH2_ACCESS_TOKEN="OAUTH_ACCESS_TOKEN"
MANAGER_CUSTOMER_ID="MANAGER_CUSTOMER_ID"
CUSTOMER_ID="CUSTOMER_ID"

أرقام تعريف العناصر الاختيارية الإضافية

تعمل بعض الأمثلة التالية على ميزانيات أو حملات حالية. إذا كان لديك معرّفات لعناصر حالية تريد استخدامها مع هذه الأمثلة، أدخِلها كما هو موضّح.

BUDGET_ID=BUDGET_ID
CAMPAIGN_ID=CAMPAIGN_ID

بخلاف ذلك، سيؤدي Mutates - Creates examples إلى إنشاء ميزانية وحملة جديدتَين.

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

مقسم على صفحات

تستخدم الطريقة search تقسيم المحتوى إلى صفحات، مع حجم ثابت للصفحة يبلغ 10,000 عنصر، ويتم تحديد page_token بجانب query.

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:search" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT campaign.name,
    campaign_budget.amount_micros,
    campaign.status,
    campaign.optimization_score,
    campaign.advertising_channel_type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.bidding_strategy_type
  FROM campaign
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign.status != 'REMOVED'
",
"page_token":"${PAGE_TOKEN}"
}'

GAQL

SELECT campaign.name,
  campaign_budget.amount_micros,
  campaign.status,
  campaign.optimization_score,
  campaign.advertising_channel_type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status != 'REMOVED'
### البث تبث الدالة `searchStream` جميع النتائج في استجابة واحدة، وبالتالي، لا يتوافق الحقل `pageSize`.

curl

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:searchStream" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data '{
"query": "
  SELECT campaign.name,
    campaign_budget.amount_micros,
    campaign.status,
    campaign.optimization_score,
    campaign.advertising_channel_type,
    metrics.clicks,
    metrics.impressions,
    metrics.ctr,
    metrics.average_cpc,
    metrics.cost_micros,
    campaign.bidding_strategy_type
  FROM campaign
  WHERE segments.date DURING LAST_7_DAYS
    AND campaign.status != 'REMOVED'
"
}'

GAQL

SELECT campaign.name,
  campaign_budget.amount_micros,
  campaign.status,
  campaign.optimization_score,
  campaign.advertising_channel_type,
  metrics.clicks,
  metrics.impressions,
  metrics.ctr,
  metrics.average_cpc,
  metrics.cost_micros,
  campaign.bidding_strategy_type
FROM campaign
WHERE segments.date DURING LAST_7_DAYS
  AND campaign.status != 'REMOVED'

Mutates

يمكن إرسال عمليات تعديل متعددة (create أو update أو remove) في نص طلب JSON واحد عن طريق ملء مصفوفة operations.

إنشاء

ينشئ هذا المثال ميزانيتَين مشتركتَين للحملة في طلب واحد.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'name': 'My Campaign Budget #${RANDOM}',
      'amountMicros': 500000,
    }
  },
  {
    'create': {
      'name': 'My Campaign Budget #${RANDOM}',
      'amountMicros': 500000,
    }
  }
]
}"

يستخدم المثال التالي BUDGET_ID من ميزانية حملة حالية، ويمكنك نسخها ولصقها من ناتج الخطوة السابقة.

BUDGET_ID=BUDGET_ID

تشير الموارد إلى موارد أخرى من خلال اسم المورد. تشير الحملة التي تم إنشاؤها في المثال التالي إلى campaignBudget من خلال اسم المورد ذي القيمة النصية.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'status': 'PAUSED',
      'advertisingChannelType': 'SEARCH',
      'geoTargetTypeSetting': {
        'positiveGeoTargetType': 'PRESENCE_OR_INTEREST',
        'negativeGeoTargetType': 'PRESENCE_OR_INTEREST'
      },
      'name': 'My Search campaign #${RANDOM}',
      'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/${BUDGET_ID}',
      'targetSpend': {}
    }
  }
]
}"

التحديثات

تعديل سمات العناصر الحالية باستخدام عمليات update يستخدم المثال التالي حملة حالية، ويمكنك نسخ ولصق البيانات من ناتج الخطوة السابقة.

CAMPAIGN_ID=CAMPAIGN_ID

تتطلّب جميع التعديلات الحقل updateMask، وهو قائمة مفصولة بفواصل تتضمّن سمات JSON التي يجب أن تكون في الطلب، والتي يجب تطبيقها كتعديل. يتم محو السمات المدرَجة في updateMask وغير المتوفّرة في نص الطلب من أحد العناصر. يتم تجاهل السمات غير المدرَجة في updateMask، ولكنها مضمّنة في نص الطلب.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'update': {
      'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}',
      'name': 'A changed campaign name #${RANDOM}',
    },
    'updateMask': 'name'
  }
],
}"

إزالة

تتم إزالة العناصر من خلال تحديد اسم المورد الخاص بها كعملية remove.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'remove': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}'
  }
],
}"

حالات الفشل الجزئية

عندما تكون هناك عمليات متعددة في طلب واحد، يمكنك اختياريًا تحديد partialFailure. إذا كانت القيمة true، يتم تنفيذ العمليات الناجحة، وتعرض العمليات غير الصالحة أخطاء. في حال false، لن تنجح جميع العمليات في الطلب إلا إذا كانت جميعها صالحة.

يستخدم المثال التالي حملة حالية، ويمكنك نسخ المحتوى ولصقه من ناتج المثال إنشاء.

CAMPAIGN_ID=CAMPAIGN_ID

يحتوي الطلب التالي على عمليتَين. تحاول العملية الأولى تغيير استراتيجية عروض الأسعار للحملة المقدَّمة، بينما تحاول العملية التالية إزالة حملة تحمل رقم تعريف غير صالح. بما أنّ العملية الثانية تؤدي إلى حدوث خطأ (معرّف الحملة غير صالح) وبما أنّ قيمة partialFailure هي false، ستفشل العملية الأولى أيضًا ولن يتم تعديل استراتيجية عروض الأسعار للحملة الحالية.

curl --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaigns:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'partialFailure': false,
'operations': [
  {
    'update': {
      'resourceName': 'customers/${CUSTOMER_ID}/campaigns/${CAMPAIGN_ID}',
      'manualCpc': {
        'enhancedCpcEnabled': false
      }
    },
    'updateMask': 'manual_cpc.enhanced_cpc_enabled'
  },
  {
    'remove': 'customers/${CUSTOMER_ID}/campaigns/INVALID_CAMPAIGN_ID'
  }
]
}"

العمليات المجمَّعة

تتيح الطريقة googleAds:mutate إرسال مجموعات من العمليات مع أنواع متعدّدة من الموارد. يمكنك إرسال العديد من العمليات من أنواع مختلفة لتسلسل مجموعة من العمليات التي يجب تنفيذها كمجموعة. تنجح مجموعة العمليات إذا لم تفشل أي عملية أو إذا فشلت جميع العمليات في حال فشل أي عملية واحدة.

يوضّح هذا المثال كيفية إنشاء ميزانية حملة وحملة ومجموعة إعلانية وإعلان معًا كمجموعة واحدة من الإجراءات. تعتمد كل عملية متتالية على العملية السابقة. وفي حال تعذُّر إحداها، ستتعذّر المجموعة الكاملة من العمليات.

تُستخدَم الأعداد الصحيحة السالبة (-1 و-2 و-3) كعناصر نائبة في أسماء الموارد، ويتم ملؤها ديناميكيًا في وقت التشغيل بنتائج تسلسل العمليات.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/googleAds:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'mutateOperations': [
  {
    'campaignBudgetOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/campaignBudgets/-1',
        'name': 'My Campaign Budget #${RANDOM}',
        'deliveryMethod': 'STANDARD',
        'amountMicros': 500000,
        'explicitlyShared': false
      }
    }
  },
  {
    'campaignOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/campaigns/-2',
        'status': 'PAUSED',
        'advertisingChannelType': 'SEARCH',
        'geoTargetTypeSetting': {
          'positiveGeoTargetType': 'PRESENCE_OR_INTEREST',
          'negativeGeoTargetType': 'PRESENCE_OR_INTEREST'
        },
        'name': 'My Search campaign #${RANDOM}',
        'campaignBudget': 'customers/${CUSTOMER_ID}/campaignBudgets/-1',
        'targetSpend': {}
      }
    }
  },
  {
    'adGroupOperation': {
      'create': {
        'resourceName': 'customers/${CUSTOMER_ID}/adGroups/-3',
        'campaign': 'customers/${CUSTOMER_ID}/campaigns/-2',
        'name': 'My ad group #${RANDOM}',
        'status': 'PAUSED',
        'type': 'SEARCH_STANDARD'
      }
    }
  },
  {
    'adGroupAdOperation': {
      'create': {
        'adGroup': 'customers/${CUSTOMER_ID}/adGroups/-3',
        'status': 'PAUSED',
        'ad': {
          'responsiveSearchAd': {
            'headlines': [
              {
                'pinned_field': 'HEADLINE_1',
                'text': 'An example headline'
              },
              {
                'text': 'Another example headline'
              },
              {
                'text': 'Yet another headline'
              }
            ],
            'descriptions': [
              {
                'text': 'An example description'
              },
              {
                'text': 'Another example description'
              }
            ],
            'path1': 'all-inclusive',
            'path2': 'deals'
          },
          'finalUrls': ['https://www.example.com']
        }
      }
    }
  }
]
}"

إدارة الحساب

يمكنك إنشاء حسابات وإدراج الحسابات التي يمكن الوصول إليها وتحميل مواد عرض ثنائية.

إنشاء حسابات

إنشاء حسابات جديدة باستخدام طريقة createCustomerClient يُرجى العِلم أنّ عنوان URL يتطلّب رقم تعريف حساب إداري بدلاً من رقم تعريف حساب عميل. يتم إنشاء حساب عميل جديد ضمن الحساب الإداري.

curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'customerClient': {
  'descriptiveName': 'My Client #${RANDOM}',
  'currencyCode': 'USD',
  'timeZone': 'America/New_York'
}
}"

إدراج الحسابات التي يمكن الوصول إليها

استخدِم طلب GET بسيطًا إلى طريقة listAccessibleCustomers للحصول على قائمة بحسابات "إعلانات Google" التي يمكن الوصول إليها باستخدام رمز الوصول المميز OAuth 2.0 المحدّد. يجب عدم استخدام أي أرقام تعريفية لحسابات إدارية أو حسابات عملاء في هذا الطلب.

curl -f --request GET "https://googleads.googleapis.com/v${API_VERSION}/customers:listAccessibleCustomers" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \

تحميل مواد العرض الثنائية

يتم استخدام الطريقة assets:mutate لتحميل مواد العرض وإدارتها. يتم ترميز البيانات الثنائية، مثل صورة، كسلسلة باستخدام ترميز base64 العادي مع إضافة مساحة فارغة. يتم قبول ترميز base64 العادي أو الآمن مع عنوان URL، سواء مع إضافة مساحة فارغة أو بدونها.

يشفّر هذا المثال ملف GIF بحجم بكسل واحد للحفاظ على اختصار العيّنة. من الناحية العملية، تكون حمولات data أكبر بكثير.

استخدِم أداة سطر الأوامر base64 (جزء من أدوات GNU الأساسية) لترميز صورة GIF بحجم بكسل واحد.

base64 1pixel.gif

يتم تحديد القيمة المرمَّزة بنظام base64 كسمة data في طلب إلى واجهة برمجة التطبيقات.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \
--header "Content-Type: application/json" \
--header "developer-token: ${DEVELOPER_TOKEN}" \
--header "login-customer-id: ${MANAGER_CUSTOMER_ID}" \
--header "Authorization: Bearer ${OAUTH2_ACCESS_TOKEN}" \
--data "{
'operations': [
  {
    'create': {
      'name': 'My image asset #${RANDOM}',
      'type': 'IMAGE',
      'imageAsset': {
        'data': 'R0lGODlhAQABAAAAACH5BAEAAAAALAAAAAABAAEAAAIA'
      }
    }
  }
]
}"
السابق
الأخطاء الشائعة
التالي
تجربة