أمثلة

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

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

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

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

ملاحظة مهمة: في هذه الأمثلة، نفترض أنّك تحاول الوصول إلى حساب عميل (CUSTOMER_ID) من قِبل مستخدم لديه إذن وصول إداري إلى حساب إداري (MANAGER_CUSTOMER_ID) يدير حساب العميل مباشرةً. إذا أردت بدلاً من ذلك الوصول إلى حساب عميل فردي مباشرةً، احذف العنوان login-customer-id أو اضبطه على القيمة نفسها مثل CUSTOMER_ID. يُرجى العلم أنّ بعض الأمثلة، مثل إنشاء حسابات، تتطلّب حسابًا إداريًا.

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

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

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

إذا لم تفعل ذلك، يؤدي التبديل - إنشاء أمثلة إلى إنشاء ميزانية وحملة جديدتين.

بحث

يحتوي دليل دليل طلبات البحث على العديد من نماذج التقارير التي تتوافق مع بعض شاشات "إعلانات 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}"
}'

واجهة برمجة التطبيقات Google Cloud Platform ( 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'
"
}'

واجهة برمجة التطبيقات Google Cloud Platform ( 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'

تبديل

يمكن إرسال عمليات تغيير متعدّدة (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'
      }
    }
  }
]
}"