البدء

توفِّر واجهة برمجة تطبيقات "مدير الحملة 360" إمكانية الوصول الآلي إلى المعلومات من حساب على "مدير الحملة 360". وهي تُستخدم لإدارة وإنشاء الحملات والتقارير تمامًا كما تفعل من خلال خدمات الويب "مدير الحملة 360" و"أداة إنشاء التقارير".

يوضِّح هذا الدليل كيفية بدء استخدام Campaign Manager 360 API.

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

قبل استخدام Campaign Manager 360 API، عليك اتّباع بعض الخطوات الأساسية إرضاء:

  1. يجب أن يكون لديك حساب على "مدير الحملة 360". عرض المعلنون/الوكالات للحصول على معلومات الاشتراك.

  2. يجب تفعيل إمكانية الوصول إلى واجهة برمجة التطبيقات في حسابك على "مدير الحملة 360". معظم الأقسام تكون هذه الميزة مفعّلة تلقائيًا في الحسابات وإذا لم تكن متأكدًا، تواصَل مع ممثل الحساب أو فريق دعم "مدير الحملة 360" للحصول على المساعدة

  3. يجب أن يكون لديك ملف شخصي للمستخدم يمكنه الوصول إلى هذا الحساب. هل لديك يُنشئ مشرف حساب "مدير الحملة 360" ملفًا شخصيًا لمستخدم مرتبطًا بـ لهذا الحساب.

  4. التحقّق من أذونات الملف الشخصي للمستخدِم في واجهة مستخدم "مدير الحملة 360" تتحكم هذه الأدوات ما يمكن لملف المستخدم الوصول إليه من خلال واجهة برمجة التطبيقات. لا توجد واجهة برمجة تطبيقات منفصلة الأذونات.

إنشاء مشروع

لبدء استخدام Campaign Manager 360 API، يجب أولاً إنشاء أو اختَر مشروعًا في وحدة التحكم في واجهة Google API وفعِّل واجهة برمجة التطبيقات. استخدام هذا رابط يرشدك خلال العملية ويفعّل Campaign Manager 360 API تلقائيًا.

إنشاء بيانات الاعتماد

يجب أن يتم تفويض جميع الطلبات التي ترسلها إلى Campaign Manager 360 API. للحصول على ملخّص نظرة عامة على التفويض، واقرأ عن كيفية تفويض تطبيق على Google.

سترشدك التعليمات التالية خلال عملية إنشاء بروتوكول OAuth. 2.0 معرِّف عميل لاستخدامه مع التطبيق المثبَّت المتدفق. للحصول على تعليمات حول إنشاء بيانات الاعتماد للاستخدام مع مسار حساب الخدمة، راجِع حسابات الخدمة. الدليل.

  1. اتّبِع الخطوات لضبط مشروع وحدة التحكم في واجهة Google API.

  2. افتح صفحة بيانات الاعتماد في وحدة تحكم واجهة برمجة التطبيقات.

  3. انقر على إنشاء شهادات >. معرِّف عميل OAuth.

    1. في حال لم تكن قد ضبطت شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth لهذا المشروع، في السابق، سيتم توجيهك للقيام بذلك الآن. انقر على ضبط الموافقة. SCREEN.

    2. اختَر نوع المستخدِم وانقر على إنشاء.

    3. املأ النموذج الأولي. ويمكنك تعديلها في وقت لاحق إذا لزم الأمر. (يُرجى النقر.) انقر على حفظ عند الانتهاء.

    4. انتقل مرة أخرى إلى بيانات الاعتماد > إنشاء بيانات الاعتماد > معرِّف عميل OAuth على متابعة.

  4. اختَر تطبيق سطح المكتب كنوع التطبيق وأدخِل اسمًا له، ثم انقر. إنشاء:

عند الانتهاء، سيظهر لك معرِّف عميل OAuth 2.0 والعميل. سرّي، والذي يمكنك تنزيله بتنسيق JSON وحفظه لاستخدامه في وقت لاحق.

تثبيت مكتبة برامج

تم إنشاء واجهة برمجة تطبيقات "مدير الحملة 360" استنادًا إلى HTTP وJSON، ما يتيح لأي عميل HTTP عادي إرسال الرسائل الإلكترونية. الطلبات إليه وتحليل الاستجابات.

ولكن مكتبات عملاء واجهة Google API توفر تكاملاً أفضل للّغات، والأمان المحسّن، والدعم لتقديم طلبات مُصرّح بها. العميل تتوفر المكتبات بعدد من لغات البرمجة؛ باستخدامها إلى تجنب الحاجة إلى إعداد طلبات HTTP يدويًا وتحليل الاستجابات.

للبدء، حدد لغة البرمجة التي تستخدمها والتطوير.

#C

ثبِّت أحدث مكتبة برامج لواجهة برمجة تطبيقات "مدير الحملة 360" لنظام .NET. استخدام يُنصح باستخدام NuGet لإدارة عملية التثبيت.

افتح وحدة تحكم NuGet Package Manager (وحدة تحكم NuGet Package Manager) وشغِّل الأمر التالي:

Install-Package Google.Apis.Dfareporting.v3_4

مزيد من المعلومات

Java

ثبِّت أحدث مكتبة برامج لواجهة برمجة تطبيقات "مدير الحملة 360" للغة Java. استخدام يُنصح باستخدام Maven لإدارة عملية التثبيت.

أضِف التبعية التالية إلى ملف pom.xml:

<dependency>
  <groupId>com.google.apis</groupId>
  <artifactId>google-api-services-dfareporting</artifactId>
  <version>v4-rev20220611-1.32.1</version>
  <exclusions>
    <exclusion>
      <groupId>com.google.guava</groupId>
      <artifactId>guava-jdk5</artifactId>
    </exclusion>
  </exclusions>
</dependency>

مزيد من المعلومات

PHP

ثبِّت أحدث مكتبة برامج لواجهة برمجة تطبيقات "مدير الحملة 360" للغة PHP. استخدام يُنصح باستخدام Composer لإدارة عملية التثبيت.

افتح نافذة Terminal وشغِّل الأمر التالي:

composer require google/apiclient

إذا كنت قد ثبتّ المكتبة من قبل وأردت تحديثها إلى أحدث إصدار:

composer update google/apiclient

بناءً على النظام الذي تستخدمه، قد تحتاج إلى إضافة هذه الأوامر sudo

مزيد من المعلومات

Python

ثبِّت أحدث مكتبة برامج لواجهة برمجة تطبيقات "مدير الحملة 360" للغة Python. استخدام يُنصح باستخدام pip لإدارة عملية التثبيت.

افتح نافذة Terminal وشغِّل الأمر التالي:

pip install --upgrade google-api-python-client

بناءً على النظام الذي تستخدمه، قد تحتاج إلى إضافة هذه الأوامر sudo

مزيد من المعلومات

Ruby

ثبِّت أحدث مكتبة برامج لواجهة برمجة تطبيقات "مدير الحملة 360" للغة Ruby. استخدام يُنصح باستخدام RubyGems لإدارة التثبيت.

افتح نافذة Terminal وشغِّل الأمر التالي:

gem install google-api-client

إذا كنت قد ثبتّ المكتبة من قبل وأردت تحديثها إلى أحدث إصدار:

gem update -y google-api-client

بناءً على النظام الذي تستخدمه، قد تحتاج إلى إضافة هذه الأوامر sudo

مزيد من المعلومات

يمكن العثور على المزيد من اللغات المتاحة على صفحة العميل "المكتبات".

تقديم طلب

مع إنشاء بيانات اعتماد OAuth 2.0 ومكتبة برامج مثبَّتة تلقائيًا، أصبحت جاهزًا لبدء استخدام Campaign Manager 360 API. اعرف كيف لتفويض عميلك وإعداده وتقديم طلبك الأول من خلال اتباع البدء السريع أدناه.

#C

  1. حمِّل ملف أسرار العميل وأنشِئ بيانات اعتماد التفويض.

    سيُطلب منك قبول مطالبة التفويض في المتصفّح الذي تستخدمه في المرة الأولى التي تنفذ فيها هذه الخطوة. قبل الموافقة، تأكَّد من تسجيل الدخول باستخدام حساب على Google لديه إذن الوصول إلى "مدير الحملة 360". سيتم تفويض تطبيقك للوصول إلى البيانات نيابةً عن الحساب الذي تم تسجيل الدخول إليه حاليًا. 

    // Load client secrets from the specified JSON file.
GoogleClientSecrets clientSecrets;
using(Stream json = new FileStream(pathToJsonFile, FileMode.Open, FileAccess.Read)) {
  clientSecrets = GoogleClientSecrets.Load(json);
}

// Create an asynchronous authorization task.
//
// Note: providing a data store allows auth credentials to be cached, so they survive multiple
// runs of the application. This avoids prompting the user for authorization every time the
// access token expires, by remembering the refresh token. The "user" value is used to
// identify a specific set of credentials within the data store. You may provide different
// values here to persist credentials for multiple users to the same data store.
Task<UserCredential> authorizationTask = GoogleWebAuthorizationBroker.AuthorizeAsync(
    clientSecrets.Secrets,
    OAuthScopes,
    "user",
    CancellationToken.None,
    dataStore);

// Authorize and persist credentials to the data store.
UserCredential credential = authorizationTask.Result;

  2. أنشئ برنامج إعداد تقارير Dfa معتمدًا.

    // Create a Dfareporting service object.
//
// Note: application name should be replaced with a value that identifies your application.
service = new DfareportingService(
    new BaseClientService.Initializer {
      HttpClientInitializer = credential,
      ApplicationName = "C# installed app sample"
    }
);

  3. نفِّذ عملية.

    // Retrieve and print all user profiles for the current authorized user.
UserProfileList profiles = service.UserProfiles.List().Execute();

foreach (UserProfile profile in profiles.Items) {
  Console.WriteLine("Found user profile with ID {0} and name \"{1}\".",
      profile.ProfileId, profile.UserName);
}

Java

  1. حمِّل ملف أسرار العميل وأنشِئ بيانات اعتماد التفويض.

    سيُطلب منك قبول مطالبة التفويض في المتصفّح الذي تستخدمه في المرة الأولى التي تنفذ فيها هذه الخطوة. قبل الموافقة، تأكَّد من تسجيل الدخول باستخدام حساب على Google لديه إذن الوصول إلى "مدير الحملة 360". سيتم تفويض تطبيقك للوصول إلى البيانات نيابةً عن الحساب الذي تم تسجيل الدخول إليه حاليًا. 

    // Load the client secrets JSON file.
GoogleClientSecrets clientSecrets =
    GoogleClientSecrets.load(
        jsonFactory, Files.newBufferedReader(Paths.get(pathToClientSecretsFile), UTF_8));

// Set up the authorization code flow.
//
// Note: providing a DataStoreFactory allows auth credentials to be cached, so they survive
// multiple runs of the program. This avoids prompting the user for authorization every time the
// access token expires, by remembering the refresh token.
GoogleAuthorizationCodeFlow flow =
    new GoogleAuthorizationCodeFlow.Builder(
            httpTransport, jsonFactory, clientSecrets, OAUTH_SCOPES)
        .setDataStoreFactory(dataStoreFactory)
        .build();

// Authorize and persist credentials to the data store.
//
// Note: the "user" value below is used to identify a specific set of credentials in the data
// store. You may provide different values here to persist credentials for multiple users to
// the same data store.
Credential credential =
    new AuthorizationCodeInstalledApp(flow, new LocalServerReceiver()).authorize("user");

  2. أنشئ برنامج إعداد تقارير Dfa معتمدًا.

    // Create a Dfareporting client instance.
//
// Note: application name below should be replaced with a value that identifies your
// application. Suggested format is "MyCompany-ProductName/Version.MinorVersion".
Dfareporting reporting =
    new Dfareporting.Builder(credential.getTransport(), credential.getJsonFactory(), credential)
        .setApplicationName("dfareporting-java-installed-app-sample")
        .build();

  3. نفِّذ عملية.

    // Retrieve and print all user profiles for the current authorized user.
UserProfileList profiles = reporting.userProfiles().list().execute();
for (int i = 0; i < profiles.getItems().size(); i++) {
  System.out.printf("%d) %s%n", i + 1, profiles.getItems().get(i).getUserName());
}

PHP

  1. حمِّل ملف أسرار العميل وأنشِئ بيانات اعتماد التفويض.

    سيُطلب منك قبول مطالبة التفويض في المتصفّح الذي تستخدمه في المرة الأولى التي تنفذ فيها هذه الخطوة. قبل الموافقة، تأكَّد من تسجيل الدخول باستخدام حساب على Google لديه إذن الوصول إلى "مدير الحملة 360". سيتم تفويض تطبيقك للوصول إلى البيانات نيابةً عن الحساب الذي تم تسجيل الدخول إليه حاليًا. 

    // Create a Google_Client instance.
//
// Note: application name should be replaced with a value that identifies
// your application. Suggested format is "MyCompany-ProductName".
$client = new Google_Client();
$client->setAccessType('offline');
$client->setApplicationName('PHP installed app sample');
$client->setRedirectUri(self::OAUTH_REDIRECT_URI);
$client->setScopes(self::$OAUTH_SCOPES);

// Load the client secrets file.
$client->setAuthConfig($pathToJsonFile);

// Try to load cached credentials from the token store. Using a token store
// allows auth credentials to be cached, so they survive multiple runs of
// the application. This avoids prompting the user for authorization every
// time the access token expires, by remembering the refresh token.
if (file_exists($tokenStore) && filesize($tokenStore) > 0) {
    $client->setAccessToken(file_get_contents($tokenStore));
} else {
    // If no cached credentials were found, authorize and persist
    // credentials to the token store.
    print 'Open this URL in your browser and authorize the application.';
    printf("\n\n%s\n\n", $client->createAuthUrl());
    print 'Enter the authorization code: ';
    $code = trim(fgets(STDIN));
    $client->authenticate($code);

    file_put_contents($tokenStore, json_encode($client->getAccessToken()));
}

  2. أنشئ برنامج إعداد تقارير Dfa معتمدًا.

    // Create a Dfareporting service object.
$service = new Google_Service_Dfareporting($client);

  3. نفِّذ عملية.

    // Retrieve and print all user profiles for the current authorized user.
$result = $service->userProfiles->listUserProfiles();
foreach ($result['items'] as $userProfile) {
    printf(
        "User profile \"%s\" (ID: %d) found for account %d.\n",
        $userProfile->getUserName(),
        $userProfile->getProfileId(),
        $userProfile->getAccountId()
    );
}

Python

  1. حمِّل ملف أسرار العميل وأنشِئ بيانات اعتماد التفويض.

    سيُطلب منك قبول مطالبة التفويض في المتصفّح الذي تستخدمه في المرة الأولى التي تنفذ فيها هذه الخطوة. قبل الموافقة، تأكَّد من تسجيل الدخول باستخدام حساب على Google لديه إذن الوصول إلى "مدير الحملة 360". سيتم تفويض تطبيقك للوصول إلى البيانات نيابةً عن الحساب الذي تم تسجيل الدخول إليه حاليًا. 

    # Set up a Flow object to be used if we need to authenticate.
flow = client.flow_from_clientsecrets(
    path_to_client_secrets_file, scope=OAUTH_SCOPES)

# Check whether credentials exist in the credential store. Using a credential
# store allows auth credentials to be cached, so they survive multiple runs
# of the application. This avoids prompting the user for authorization every
# time the access token expires, by remembering the refresh token.
storage = Storage(CREDENTIAL_STORE_FILE)
credentials = storage.get()

# If no credentials were found, go through the authorization process and
# persist credentials to the credential store.
if credentials is None or credentials.invalid:
  credentials = tools.run_flow(flow, storage,
                               tools.argparser.parse_known_args()[0])

# Use the credentials to authorize an httplib2.Http instance.
http = credentials.authorize(httplib2.Http())

  2. أنشئ برنامج إعداد تقارير Dfa معتمدًا.

    # Construct a service object via the discovery service.
service = discovery.build('dfareporting', 'v4', http=http)

  3. نفِّذ عملية.

    # Construct the request.
request = service.userProfiles().list()

# Execute request and print response.
response = request.execute()

for profile in response['items']:
  print('Found user profile with ID %s and user name "%s".' %
        (profile['profileId'], profile['userName']))

Ruby

  1. حمِّل ملف أسرار العميل وأنشِئ بيانات اعتماد التفويض.

    سيُطلب منك قبول مطالبة التفويض في المتصفّح الذي تستخدمه في المرة الأولى التي تنفذ فيها هذه الخطوة. قبل الموافقة، تأكَّد من تسجيل الدخول باستخدام حساب على Google لديه إذن الوصول إلى "مدير الحملة 360". سيتم تفويض تطبيقك للوصول إلى البيانات نيابةً عن الحساب الذي تم تسجيل الدخول إليه حاليًا. 

    # Load client ID from the specified file.
client_id = Google::Auth::ClientId.from_file(path_to_json_file)

# Set up the user authorizer.
#
# Note: providing a token store allows auth credentials to be cached, so they
# survive multiple runs of the application. This avoids prompting the user for
# authorization every time the access token expires, by remembering the
# refresh token.
authorizer = Google::Auth::UserAuthorizer.new(
  client_id, [API_NAMESPACE::AUTH_DFAREPORTING], token_store
)

# Authorize and persist credentials to the data store.
#
# Note: the 'user' value below is used to identify a specific set of
# credentials in the token store. You may provide different values here to
# persist credentials for multiple users to the same token store.
authorization = authorizer.get_credentials('user')
if authorization.nil?
  puts format(
    "Open this URL in your browser and authorize the application.\n\n%s" \
    "\n\nEnter the authorization code:",
    authorizer.get_authorization_url(base_url: OAUTH_REDIRECT_URI)
  )
  code = STDIN.gets.chomp
  authorization = authorizer.get_and_store_credentials_from_code(
    base_url: OAUTH_REDIRECT_URI, code: code, user_id: 'user'
  )
end

  2. أنشئ برنامج إعداد تقارير Dfa معتمدًا.

    # Create a Dfareporting service object.
#
# Note: application name should be replaced with a value that identifies
# your application. Suggested format is "MyCompany-ProductName".
service = API_NAMESPACE::DfareportingService.new
service.authorization = authorization
service.client_options.application_name = 'Ruby installed app sample'
service.client_options.application_version = '1.0.0'

  3. نفِّذ عملية.

    // Retrieve and print all user profiles for the current authorized user.
UserProfileList profiles = service.UserProfiles.List().Execute();

foreach (UserProfile profile in profiles.Items) {
  Console.WriteLine("Found user profile with ID {0} and name \"{1}\".",
      profile.ProfileId, profile.UserName);
}

مزيد من المعلومات

انتقل إلى مرجع واجهة برمجة التطبيقات للتعرف على جميع الخدمات التي التي يجب أن تقدمها واجهة برمجة التطبيقات. تحتوي كل صفحة تفاصيل طريقة على واجهة برمجة تطبيقات مضمَّنة Explorer (المستكشف) الذي يمكنك استخدامه لإجراء طلبات اختبار مباشرة من المتصفح.

يمكنك الاطّلاع على أدلتنا الأخرى التي تتناول مواضيع متقدمة وتوفّر معلومات شاملة أمثلة للمهام الشائعة.

عندما تكون مستعدًا لبدء كتابة التعليمات البرمجية، يمكنك الاطّلاع على عيّنات التعليمات البرمجية، والتي قد يتم تعديلها موسع لتناسب احتياجاتك.