البدء

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

يوضّح هذا الدليل كيفية بدء استخدام واجهة برمجة تطبيقات "مدير الحملة 360".

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

قبل استخدام واجهة برمجة تطبيقات "مدير الحملة 360"، هناك بعض المتطلبات الأساسية التي عليك تلبيتها:

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

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

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

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

إنشاء مشروع

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

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

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

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

  1. اتّبِع خطوات ضبط مشروع Google API Console.

  2. افتح صفحة بيانات الاعتماد في وحدة تحكم واجهة برمجة التطبيقات.
  3. انقر على إنشاء شهادات > معرِّف عميل OAuth.

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

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

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

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

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

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

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

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

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

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

C#‎

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

انقر على NuGet Package Manager Console (وحدة التحكُّم في إدارة الحِزم) وشغِّل الأمر التالي:

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>

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

‫2,999

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

افتَح نافذة طرفية وفعِّل الأمر التالي:

composer require google/apiclient

إذا سبق لك تثبيت المكتبة وتريد فقط التحديث إلى أحدث إصدار:

composer update google/apiclient

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

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

لغة Python

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

افتَح نافذة طرفية وفعِّل الأمر التالي:

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

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

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

Ruby

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

افتَح نافذة طرفية وفعِّل الأمر التالي:

gem install google-api-client

إذا سبق لك تثبيت المكتبة وتريد فقط التحديث إلى أحدث إصدار:

gem update -y google-api-client

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

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

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

تقديم طلب

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

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. إنشاء برنامج Dfareporting مُعتمَد.

    // 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. إنشاء برنامج Dfareporting مُعتمَد.

    // 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());
    }
    

‫2,999

  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. إنشاء برنامج Dfareporting مُعتمَد.

    // 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. إنشاء برنامج Dfareporting مُعتمَد.

    # 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. إنشاء برنامج Dfareporting مُعتمَد.

    # 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);
    }
    

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

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

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

عندما تكون مستعدًا لبدء كتابة الرمز، يمكنك استكشاف مجموعتنا الشاملة من عيّنات الرموز التي يمكن تعديلها وتوسيعها لتناسب احتياجاتك.