أمثلة

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

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

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

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

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

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

API_VERSION="16"
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

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

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

مرقّمة

تستخدم الطريقة search التقسيم على صفحات، مع معلَمة pageSize قابلة للتعديل تم تحديدها إلى جانب 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 '{
"pageSize": 10,
"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'
"
}'

مورّد Google Analytics

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'
"
}'

مورّد Google Analytics

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'

تغيير

يمكن إرسال عمليات التبديل المتعدّدة (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 بحجم 1 بكسل للحفاظ على وضوح العيّنة. من الناحية العملية، تكون حمولات data أكبر بكثير.

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

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'
      }
    }
  }
]
}"
السابق
طرق أخرى
التالي
تجربة