این صفحه به‌وسیله ‏Cloud Translation API‏ ترجمه شده است.

شروع کنید

می‌توانید از Google Ad Manager API برای ساخت برنامه‌هایی استفاده کنید که موجودی را مدیریت می‌کنند، سفارش‌ها ایجاد می‌کنند، گزارش‌ها را جمع‌آوری می‌کنند و موارد دیگر.

Ad Manager API از SOAP استفاده می کند. برای کمک به شما برای شروع، ما کتابخانه های سرویس گیرنده را برای جاوا، دات نت، پایتون، پی اچ پی و روبی ارائه می دهیم.

برای ایجاد اولین درخواست API خود، این مراحل را دنبال کنید:

اگر قبلاً ندارید، برای یک حساب Ad Manager ثبت نام کنید. همچنین اگر می خواهید API را در یک محیط جداگانه آزمایش کنید، می توانید یک شبکه آزمایشی ایجاد کنید. توجه داشته باشید که برای اهداف آزمایشی به حساب AdSense نیاز ندارید.

کد شبکه خود را یادداشت کنید. وقتی وارد شبکه خود می شوید می توانید این را در URL پیدا کنید. برای مثال، در URL https://admanager.google.com/1234#home ، 1234 کد شبکه شما است.

اعتبار احراز هویت ایجاد کنید

باید همه درخواست‌های Ad Manager API را با استفاده از OAuth 2.0 احراز هویت کنید. مراحل زیر موارد استفاده از دسترسی به داده‌های Ad Manager خود را پوشش می‌دهد. برای جزئیات بیشتر و گزینه‌های دیگر، احراز هویت را ببینید.

صفحه Google API Console Credentials را باز کنید
از منوی پروژه، Create project را انتخاب کنید، نامی برای پروژه وارد کنید و در صورت تمایل، شناسه پروژه ارائه شده را ویرایش کنید. روی ایجاد کلیک کنید.
در صفحه اعتبارنامه ها، Create credentials را انتخاب کنید، سپس کلید حساب کاربری را انتخاب کنید.
حساب جدید سرویس را انتخاب کنید و JSON به عنوان نوع کلید انتخاب کنید.
برای دانلود فایل حاوی کلید خصوصی روی Create کلیک کنید.

شبکه Ad Manager خود را پیکربندی کنید

به Google Ad Manager وارد شوید .
در نوار کناری، روی Admin > تنظیمات جهانی کلیک کنید.
در قسمت تنظیمات عمومی > دسترسی به Api، روی نوار لغزنده به Enabled کلیک کنید.
روی دکمه ذخیره در پایین صفحه کلیک کنید.

مشتری خود را تنظیم کنید

یکی از کتابخانه های مشتری Ad Manager را دانلود کنید. کتابخانه‌ها عملکردها و ویژگی‌هایی را ارائه می‌دهند که توسعه برنامه‌ها را آسان‌تر و سریع‌تر می‌کنند.

برگه‌های زیر شروع سریعی را برای کدنویسی در هر یک از زبان‌هایی که کتابخانه مشتری برای آن‌ها وجود دارد، ارائه می‌کنند.

Java

در اینجا یک مثال اساسی است که نحوه استفاده از کتابخانه کلاینت جاوا را نشان می دهد. برای اطلاعات بیشتر درباره استفاده، به فایل README در توزیع کتابخانه مشتری مراجعه کنید.

اعتبارنامه خود را تنظیم کنید

دستور زیر را در یک پوسته اجرا کنید:

curl https://raw.githubusercontent.com/googleads/googleads-java-lib/main/examples/admanager_axis/src/main/resources/ads.properties -o ~/ads.properties

فایل ~/ads.properties را باز کنید و فیلدهای زیر را پر کنید:

[...]
api.admanager.applicationName=INSERT_APPLICATION_NAME_HERE
api.admanager.jsonKeyFilePath=INSERT_PATH_TO_JSON_KEY_FILE_HERE
api.admanager.networkCode=INSERT_NETWORK_CODE_HERE
[...]

وابستگی ها را مشخص کنید

فایل pom.xml خود را ویرایش کنید و موارد زیر را به تگ dependencies اضافه کنید. می توانید آخرین شماره نسخه را در Github پیدا کنید.

<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>ads-lib</artifactId>
  <version>RELEASE</version>
</dependency>
<dependency>
  <groupId>com.google.api-ads</groupId>
  <artifactId>dfp-axis</artifactId>
  <version>RELEASE</version>
</dependency>

کدی بنویس و درخواست بده!

import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.ads.admanager.axis.factory.AdManagerServices;
import com.google.api.ads.admanager.axis.v202402.Network;
import com.google.api.ads.admanager.axis.v202402.NetworkServiceInterface;
import com.google.api.ads.admanager.lib.client.AdManagerSession;
import com.google.api.client.auth.oauth2.Credential;

public class App {
  public static void main(String[] args) throws Exception {
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.AD_MANAGER)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdManagerSession.
    AdManagerSession session = new AdManagerSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    // Construct a Google Ad Manager service factory, which can only be used once per
    // thread, but should be reused as much as possible.
    AdManagerServices adManagerServices = new AdManagerServices();

    // Retrieve the appropriate service
    NetworkServiceInterface networkService = adManagerServices.get(session,
        NetworkServiceInterface.class);

    // Make a request
    Network network = networkService.getCurrentNetwork();

    System.out.printf("Current network has network code '%s' and display" +
        " name '%s'.%n", network.getNetworkCode(), network.getDisplayName());
  }
}

در GitHub مشاهده کنید

Python

در اینجا یک مثال اساسی است که نحوه استفاده از کتابخانه کلاینت پایتون را نشان می دهد. کتابخانه Client Python از Python نسخه 3.6+ پشتیبانی می کند. برای اطلاعات بیشتر درباره استفاده، به فایل README در توزیع کتابخانه مشتری مراجعه کنید.

کتابخانه را نصب کنید و اعتبار خود را تنظیم کنید.
دستورات زیر را در یک پوسته اجرا کنید:
```
pip install googleads
curl https://raw.githubusercontent.com/googleads/googleads-python-lib/main/googleads.yaml \
     -o ~/googleads.yaml
```

فایل ~/googleads.yaml خود را تنظیم کنید.

فیلدهای زیر را پر کنید:

ad_manager:
  application_name: INSERT_APPLICATION_NAME_HERE
  network_code: INSERT_NETWORK_CODE_HERE
  path_to_private_key_file: INSERT_PATH_TO_FILE_HERE

کدی را اجرا کنید و درخواست بدهید.

# Import the library.
from googleads import ad_manager

# Initialize a client object, by default uses the credentials in ~/googleads.yaml.
client = ad_manager.AdManagerClient.LoadFromStorage()

# Initialize a service.
network_service = client.GetService('NetworkService', version='v202402')

# Make a request.
current_network = network_service.getCurrentNetwork()

print("Current network has network code '%s' and display name '%s'." %
        (current_network['networkCode'], current_network['displayName']))

در GitHub مشاهده کنید

PHP

در اینجا یک مثال اساسی است که نحوه استفاده از کتابخانه مشتری PHP را نشان می دهد.

کتابخانه را نصب کنید و اطلاعات کاربری خود را تنظیم کنید.
دستورات زیر را در یک پوسته برای نصب کتابخانه مشتری و دانلود فایل adsapi_php.ini در فهرست اصلی خود اجرا کنید:
```
composer require googleads/googleads-php-lib
curl https://raw.githubusercontent.com/googleads/googleads-php-lib/main/examples/AdManager/adsapi_php.ini -o ~/adsapi_php.ini
```

فایل ~/adsapi_php.ini خود را راه اندازی کنید.

فیلدهای زیر را پر کنید:

[AD_MANAGER]
networkCode = "INSERT_NETWORK_CODE_HERE"
applicationName = "INSERT_APPLICATION_NAME_HERE"

[OAUTH2]
jsonKeyFilePath = "INSERT_ABSOLUTE_PATH_TO_OAUTH2_JSON_KEY_FILE_HERE"
scopes = "https://www.googleapis.com/auth/dfp"

کدی را اجرا کنید و درخواست بدهید!

این کد مثال باید از خط فرمان اجرا شود نه از مرورگر. فایل حاوی این کد باید در ریشه دایرکتوری پروژه قرار داشته باشد، جایی که composer require اجرا شده است.

<?php
require 'vendor/autoload.php';
use Google\AdsApi\AdManager\AdManagerSession;
use Google\AdsApi\AdManager\AdManagerSessionBuilder;
use Google\AdsApi\AdManager\v202402\ApiException;
use Google\AdsApi\AdManager\v202402\ServiceFactory;
use Google\AdsApi\Common\OAuth2TokenBuilder;

// Generate a refreshable OAuth2 credential for authentication.
$oAuth2Credential = (new OAuth2TokenBuilder())
    ->fromFile()
    ->build();
// Construct an API session configured from a properties file and the OAuth2
// credentials above.
$session = (new AdManagerSessionBuilder())
    ->fromFile()
    ->withOAuth2Credential($oAuth2Credential)
    ->build();

// Get a service.
$serviceFactory = new ServiceFactory();
$networkService = $serviceFactory->createNetworkService($session);

// Make a request
$network = $networkService->getCurrentNetwork();
printf(
    "Network with code %d and display name '%s' was found.\n",
    $network->getNetworkCode(),
    $network->getDisplayName()
);

در GitHub مشاهده کنید

.NET

در اینجا یک مثال اساسی است که نحوه استفاده از کتابخانه کلاینت دات نت را نشان می دهد

یک پروژه جدید ایجاد کنید
ویژوال استودیو را باز کنید و یک پروژه جدید (برنامه کنسول) ایجاد کنید.
ارجاعات کتابخانه مورد نیاز را به پروژه خود اضافه کنید
یک وابستگی nuget برای Google.Dfp اضافه کنید.
App.config خود را راه اندازی کنید
src\App.config را در فهرست پروژه خود کپی کنید و آن را به پروژه خود اضافه کنید. اگر برنامه شما App.config خاص خود را دارد، می توانید گره های زیر را در App.config خود کپی کنید:
- پیکربندی/AdManagerApi
- configuration/configSections/section[name="AdManagerApi"]
- configuration/system.net

راه اندازی اعتبار

App.config را باز کنید و کلیدهای زیر را ویرایش کنید:

<add key="ApplicationName" value="INSERT_YOUR_APPLICATION_NAME_HERE" />
<add key="NetworkCode" value="INSERT_YOUR_NETWORK_CODE_HERE" />
<add key="OAuth2Mode" value="SERVICE_ACCOUNT" />
<add key="OAuth2SecretsJsonPath" value="INSERT_OAUTH2_SECRETS_JSON_FILE_PATH_HERE" />

با کتابخانه تماس بگیرید

همانطور که در قطعه کد C# زیر نشان داده شده است، می توانید کتابخانه را فراخوانی کنید

در GitHub مشاهده کنید

AdManagerUser user = new AdManagerUser();
      using (InventoryService inventoryService = user.GetService<InventoryService>())
            {
                // Create a statement to select ad units.
                int pageSize = StatementBuilder.SUGGESTED_PAGE_LIMIT;
                StatementBuilder statementBuilder =
                    new StatementBuilder().OrderBy("id ASC").Limit(pageSize);

                // Retrieve a small amount of ad units at a time, paging through until all
                // ad units have been retrieved.
                int totalResultSetSize = 0;
                do
                {
                    AdUnitPage page =
                        inventoryService.getAdUnitsByStatement(statementBuilder.ToStatement());

                    // Print out some information for each ad unit.
                    if (page.results != null)
                    {
                        totalResultSetSize = page.totalResultSetSize;
                        int i = page.startIndex;
                        foreach (AdUnit adUnit in page.results)
                        {
                            Console.WriteLine(
                                "{0}) Ad unit with ID \"{1}\" and name \"{2}\" was found.", i++,
                                adUnit.id, adUnit.name);
                        }
                    }

                    statementBuilder.IncreaseOffsetBy(pageSize);
                } while (statementBuilder.GetOffset() < totalResultSetSize);

                Console.WriteLine("Number of results found: {0}", totalResultSetSize);
            }

اگر نمی‌خواهید اعتبار خود را در App.config خود تنظیم کنید، برای روش‌های جایگزین برای استفاده از کلاس AdManagerUser به این مقاله ویکی مراجعه کنید. برای اطلاعات بیشتر در مورد استفاده از کتابخانه مشتری دات نت، به README مراجعه کنید. اگر می‌خواهید بدون کتابخانه مشتری در دات‌نت توسعه دهید، لطفاً به مقاله ویکی NoClientLibrary مراجعه کنید.

Ruby

در اینجا یک مثال اساسی است که نحوه استفاده از کتابخانه کلاینت Ruby را نشان می دهد. کتابخانه کلاینت Ruby به Ruby 2.1 یا جدیدتر نیاز دارد.

Ruby gem را نصب کنید و فایل پیکربندی را دریافت کنید.
دستورات زیر را در یک پوسته اجرا کنید:
```
gem install google-dfp-api
curl https://raw.githubusercontent.com/googleads/google-api-ads-ruby/main/ad_manager_api/ad_manager_api.yml -o ~/ad_manager_api.yml
```
اگر در هر زمانی هنگام نصب جم‌های خود با خطای « cannot load such file -- mkmf (LoadError) » مواجه شدید، ممکن است نیاز به نصب کتابخانه‌های توسعه Ruby اضافی مانند ruby-dev، ruby-devel، xcode-select و غیره داشته باشید. برای محیط خاص شما
اعتبارنامه خود را تنظیم کنید
فیلدهای مورد نیاز را در فایل ~/ad_manager_api.yml پر کنید. اگر قبلاً یک فایل کلید OAuth2 ندارید، باید مراحل ایجاد اعتبارنامه OAuth2 خود را دنبال کنید.
```
:authentication:
  :oauth2_keyfile: INSERT_PATH_TO_JSON_KEY_FILE_HERE
  :application_name: INSERT_APPLICATION_NAME_HERE
  :network_code: INSERT_NETWORK_CODE_HERE
```

کدی بنویس و درخواست بده!

# Import the library.
require 'ad_manager_api'

# Initialize an Ad Manager client instance (uses credentials in ~/ad_manager_api.yml by default).
ad_manager = AdManagerApi::Api.new

# Get a service instance.
network_service = ad_manager.service(:NetworkService, :v202402)

# Make a request.
network = network_service.get_current_network()

puts "The current network is %s (%d)." %
        [network[:display_name], network[:network_code]]

در GitHub مشاهده کنید

مراحل دقیق‌تر برای شروع را می‌توانید در فایل README که با کتابخانه کلاینت Ruby توزیع شده است، پیدا کنید. همچنین، کتابخانه نمونه کامل ما را برای روبی بررسی کنید.

مراحل بعدی

هنگامی که یک کتابخانه مشتری راه اندازی و اجرا می کنید، نمونه های ارائه شده را تغییر دهید تا آنها را برای نیازهای خود گسترش دهید.

برای کسب اطلاعات بیشتر در مورد API ، اسناد مرجع را مرور کنید.

اگر به کمک نیاز دارید، از صفحه پشتیبانی ما دیدن کنید.

شروع کنید

به شبکه Ad Manager دسترسی پیدا کنید

اعتبار احراز هویت ایجاد کنید

شبکه Ad Manager خود را پیکربندی کنید

مشتری خود را تنظیم کنید

Java

Python

PHP

.NET

Ruby

مراحل بعدی