أمثلة

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

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

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

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

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

أدخِل بيانات اعتماد الحساب وأرقام تعريفه أدناه، ثم انسخها والصقها في الطرفية لتهيئة متغيرات البيئة المستخدمة في الأمثلة اللاحقة. يقدم دليل التفويض إرشادات لإنشاء رمز الدخول إلى 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'
      }
    }
  }
]
}"
السابق
طرق أخرى
التالي
تجربة