‫Google برای ترجمه محتوا به زبان ترجیحی شما از فناوری هوشواره استفاده می‌کند. ترجمه‌های هوشواره‌ای ممکن است اشتباه داشته باشند.

مثال‌ها

این راهنما حاوی نمونه‌هایی از فراخوانی مستقیم نقاط پایانی REST بدون استفاده از کتابخانه کارخواه است.

برای نمونه‌های کد دقیق‌تر، مخزن GitHub نمونه‌های کد REST را بررسی کنید.

برای مشاهده بدنه درخواست و پاسخ برای هر روش میانای برنامه‌سازی کاربردی، به اسناد مرجع برای نقاط پایانی سرویس خاص مراجعه کنید.

برای مثال، صفحه مرجع برای GoogleAdsService.Search بدنه درخواست و پاسخ را برای روش Search نشان می‌دهد.

پیش‌نیازها

همه نمونه‌های نشان‌داده‌شده در اینجا برای کپی و جای‌گذاری در یک bash shell بااستفاده از فرمان curl درنظر گرفته شده‌اند.

همچنین به پروژه Google Cloud نیاز دارید، دسترسی حساب آزمایشی کافی است، و حساب مدیر Google Ads که حداقل یک حساب مشتری داشته باشد.

متغیرهای محیطی

اعتبارنامه‌ها و شناسه‌های حساب را همان‌طور که نشان داده شده است وارد کنید، سپس آن‌ها را در پایانه خود کپی و جای‌گذاری کنید تا متغیرهای محیطی استفاده‌شده در مثال‌های بعدی را پیکربندی کنید. راهنمای مجوز دستورالعمل‌هایی برای تولید کد دسترسی OAuth 2.0 ارائه می‌دهد.

API_VERSION="26"
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 بودجه و کمپین جدیدی ایجاد می‌کنند.

جستجو

راهنمای Query Cookbook حاوی نمونه‌های گزارش‌دهی بسیاری است که با برخی‌از صفحه‌های پیش‌فرض Google Ads مطابقت دارد و با همان متغیرهای محیطی استفاده‌شده در این راهنما کار می‌کند. ابزار تعاملی پرسمان‌ساز ما نیز منبعی عالی برای ساختن پرسمان‌های سفارشی به‌صورت تعاملی است.

صفحه‌بندی‌شده

روش search از صفحه‌بندی استفاده می‌کند، با اندازه صفحه ثابت ۱۰٬۰۰۰ مورد و 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 "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 "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'

جهش می‌کند

با پر کردن آرایه operations، می‌توان چندین عملیات جهش (create، update، یا remove) را در یک بدنه درخواست JSON ارسال کرد.

ایجاد می‌کند

این مثال دو بودجه پویش مشترک را در یک درخواست ایجاد می‌کند.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/campaignBudgets:mutate" \
--header "Content-Type: application/json" \
--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 "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 "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 "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 "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 "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، حساب‌های جدید ایجاد کنید. توجه داشته باشید که نشانی وب به شناسه حساب مدیر به‌جای شناسه حساب مشتری نیاز دارد. حساب مشتری جدیدی در حساب مدیر ایجاد می‌شود.

curl f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${MANAGER_CUSTOMER_ID}:createCustomerClient" \
--header "Content-Type: application/json" \
--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 Ads قابل‌دسترسی با کد دسترسی OAuth 2.0 داده‌شده را دریافت کنید. هیچ شناسه حساب مدیر یا کارخواهی نباید در این درخواست استفاده شود.

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

بارگذاری کردن دارایی‌های دودویی

از روش assets:mutate برای بارگذاری و مدیریت دارایی‌ها استفاده می‌شود. داده‌های دودویی، مانند تصویر، به‌عنوان رشته بااستفاده از کدبندی استاندارد base64 با لایه‌گذاری کدبندی می‌شوند. کدبندی بیس۶۴ استاندارد یا URL-safe با یا بدون لایه‌گذاری پذیرفته می‌شود.

این نمونه یک GIF یک پیکسلی را کدگذاری می‌کند تا نمونه مختصر بماند. در عمل، بارداده‌های data بسیار بزرگ‌تر هستند.

از ابزار کمکی خط فرمان base64 (بخشی از ابزارهای کمکی هسته GNU) برای کدبندی تصویر GIF‏ ۱ پیکسلی استفاده کنید.

base64 1pixel.gif

مقدار کدبندی‌شده با base64 به‌عنوان مشخصه data در درخواست API مشخص می‌شود.

curl -f --request POST "https://googleads.googleapis.com/v${API_VERSION}/customers/${CUSTOMER_ID}/assets:mutate" \
--header "Content-Type: application/json" \
--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'
      }
    }
  }
]
}"

مثال‌ها با مجموعه‌ها، منظم بمانید ذخیره و طبقه‌بندی محتوا براساس اولویت‌های شما.

پیش‌نیازها

متغیرهای محیطی

شناسه‌های شیء اختیاری اضافی

جستجو

صفحه‌بندی‌شده

curl

GAQL

جاری‌سازی

curl

GAQL

جهش می‌کند

ایجاد می‌کند

به‌روزرسانی‌ها

برمی‌دارد

موارد ناقص ناموفق

عملیات گروه‌بندی‌شده

مدیریت حساب

ایجاد حساب

فهرست کردن حساب‌های قابل‌دسترسی

بارگذاری کردن دارایی‌های دودویی

مثال‌ها