إعداد إذن الوصول إلى واجهة برمجة التطبيقات

في ما يلي كيفية إعداد إذن الوصول إلى Data Manager API باستخدام حزمة تطوير برامج (SDK) أو REST.

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

قبل استخدام Data API، تأكَّد من توفّر ما يلي:

  1. مشروع Google Cloud
  2. حساب Google يستوفي المعيارَين التاليَين:
    1. تم منحك إذن الوصول إلى Data Manager API بعد ملء نموذج إبداء الاهتمام بـ Data Manager API. إذا كان بإمكانك الاطّلاع على صفحة تفاصيل منتج واجهة برمجة التطبيقات، يعني ذلك أنّ لديك إذن الوصول.
    2. لديه إذن serviceusage.services.enable في مشروعك على Google Cloud، أو لديه دور يتضمّن هذا الإذن. على سبيل المثال، يتضمّن كل من roles/owner وroles/serviceusage.serviceUsageAdmin الإذن serviceusage.services.enable. للاطّلاع على أذوناتك، راجِع مقالة عرض إذن الوصول الحالي.

تفعيل واجهة برمجة التطبيقات

إذا لم يسبق لك إجراء ذلك، فعِّل واجهة برمجة التطبيقات Data Manager API.

إذا لم تتمكّن من العثور على Data Manager API، تأكَّد من أنّ حسابك على Google يستوفي المتطلبات الأساسية.

إعداد المصادقة

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

النطاق https://www.googleapis.com/auth/datamanager مطلوب لأي بيانات اعتماد مستخدَمة مع Data Manager API. للاطّلاع على مثال حول كيفية استخدام النطاقات، راجِع مستندات الأمر gcloud auth application-default login.

لمزيد من المعلومات عن المصادقة وبيانات الاعتماد لتطبيقك، يُرجى الاطّلاع على طرق المصادقة في Google وطريقة عمل بيانات الاعتماد التلقائية للتطبيقات.

إعداد إذن الوصول إلى حساب التشغيل

امنح عنوان البريد الإلكتروني المرتبط بحساب المستخدم أو حساب الخدمة إذن الوصول إلى Destination.

إعداد حزمة تطوير البرامج (SDK) للغة البرمجة

على جهازك، ثبِّت حزمة تطوير البرامج (SDK) التي تختارها:

REST

  1. عدِّل العناصر النائبة في النموذج التالي، مثل OPERATING_ACCOUNT_PRODUCT وOPERATING_ACCOUNT_ID وAUDIENCE_ID، باستخدام قيم حسابك ووجهتك.
  2. استبدِل PROJECT_ID بمعرّف Google Cloud.
  3. انسخ العيّنة إلى سطر الأوامر لإرسال الطلب.

    أزِل السمة linkedAccount من الإدخال في destinations إذا لم تكن تصل إلى operationAccount باستخدام رابط منتج ثابت.

    #!/bin/bash
    
    # Uses gcloud to get an access token.
    DATA_MANAGER_ACCESS_TOKEN="$(gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/datamanager)"
    
    # Sends the request.
    curl -X POST "https://datamanager.googleapis.com/v1/audienceMembers:ingest" \
      --header "Authorization: Bearer ${DATA_MANAGER_ACCESS_TOKEN}" \
      --header "x-goog-user-project: PROJECT_ID" \
      --header "Content-Type: application/json" \
      --data @- <<EOF
    {
      "destinations": [
        {
          "operatingAccount": {
            "product": "OPERATING_ACCOUNT_PRODUCT",
            "accountId": "OPERATING_ACCOUNT_ID"
          },
          "loginAccount": {
            "product": "LOGIN_ACCOUNT_PRODUCT",
            "accountId": "LOGIN_ACCOUNT_ID"
          },
          "linkedAccount": {
            "product": "LINKED_ACCOUNT_PRODUCT",
            "accountId": "LINKED_ACCOUNT_ID"
          },
          "productDestinationId": "AUDIENCE_ID"
        }
      ],
      "audienceMembers": [
        {
          "userData": {
            "userIdentifiers": [
              {
                "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
              },
              {
                "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
              }
            ]
          }
        },
        {
          "userData": {
            "userIdentifiers": [
              {
                "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
              },
              {
                "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
              },
              {
                "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
              }
            ]
          }
        },
        {
          "userData": {
            "userIdentifiers": [
              {
                "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
              },
              {
                "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
              }
            ]
          }
        },
        {
          "userData": {
            "userIdentifiers": [
              {
                "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
              },
              {
                "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
              }
            ]
          }
        }
      ],
      "consent": {
        "adUserData": "CONSENT_GRANTED",
        "adPersonalization": "CONSENT_GRANTED"
      },
      "encoding": "HEX",
      "termsOfService": {
        "customerMatchTermsOfServiceStatus": "ACCEPTED"
      },
      "validateOnly": true
    }
    EOF
    

Java

  1. نزِّل الملف google-cloud-ads-datamanager-v1-java.tar.gz واستخرِجه.
  2. انتقِل إلى دليل google-cloud-ads-datamanager-v1-java.
  3. نفِّذ الأمر التالي لإنشاء المكتبة ونشرها في مستودع Maven المحلي لاستخدامها مع Maven أو Gradle.

    ./gradlew -Pversion=0.1.0 install
    
  4. في مشروع Java، حدِّد اعتمادية على مكتبة Data Manager API.

    Gradle:

    implementation 'com.google.cloud:gapic-google-cloud-ads-datamanager-v1-java:0.1.0'
    

    ‫Maven:

    <dependency>
      <groupId>com.google.cloud</groupId>
      <artifactId>gapic-google-cloud-ads-datamanager-v1-java</artifactId>
      <version>0.1.0</version>
    </dependency>
    
  5. Optional. الحصول على مكتبة الأدوات وعيّنات الرموز البرمجية

    1. نزِّل الملف data-manager-java.tar.gz واستخرِجه.
    2. انتقِل إلى دليل data-manager-java.
    3. بالنسبة إلى Maven أو Gradle، شغِّل الأمر التالي. ينشئ هذا الأمر مكتبة الأدوات المساعدة وينشرها في مستودع Maven المحلي.

      ./gradlew data-manager-util:install
      
    4. في مشروع Java، حدِّد عنصرًا تابعًا لمكتبة الأدوات المساعدة.

      Gradle:

      implementation 'com.google.api-ads:data-manager-util:0.1.0'
      

      ‫Maven:

      <dependency>
         <groupId>com.google.api-ads</groupId>
         <artifactId>data-manager-util</artifactId>
         <version>0.1.0</version>
      </dependency>
      
    5. لتنسيق البيانات وتشفيرها، استخدِم الأداتَين UserDataFormatter وEncrypter في مشروع Java.

    6. تصفُّح عيّنات الرموز البرمجية في الدليل الفرعي data-manager-samples لتشغيل عيّنة من سطر الأوامر، استخدِم مهمة Gradle run.

      على سبيل المثال، ينفّذ الأمر التالي IngestAudienceMembers نموذجًا ويطبع بيانًا عن الاستخدام:

      ./gradlew data-manager-samples:run \
        --args='IngestAudienceMembers --help'
      

      لمساعدتك في البدء ببعض البيانات النموذجية، استخدِم الملف على data-manager-samples/src/main/resources/sampledata/audience_members_1.csv.

Python

  1. نزِّل ads-datamanager-v1-py.tar.gz.
  2. انتقِل إلى دليل التنزيل.
  3. نفِّذ الأمر التالي لإنشاء المكتبة وإتاحتها للمشاريع الأخرى في بيئة Python نفسها:

    pip install ./ads-datamanager-v1-py.tar.gz
    
  4. في مشروع Python، حدِّد تبعية لمكتبة Data Manager API. على سبيل المثال، إذا كنت تستخدم ملف requirements.txt في مشروعك، أضِف السطر التالي إلى الملف:

    google-ads-data-manager=0.1.0
    
  5. Optional. الحصول على مكتبة الأدوات وعيّنات الرموز البرمجية

    1. نزِّل الملف data-manager-python.tar.gz واستخرِجه.
    2. انتقِل إلى دليل data-manager-python.
    3. لتثبيت مكتبة الأدوات المساعدة في بيئة Python، شغِّل الأمر التالي:

      pip install .
      
    4. في مشروع Python، حدِّد عنصرًا تابعًا لمكتبة الأدوات المساعدة. على سبيل المثال، إذا كنت تستخدم ملف requirements.txt في مشروعك، أضِف السطر التالي إلى الملف:

      google-ads-data-manager-util=0.1.0
      
    5. لتنسيق البيانات وتشفيرها، استخدِم الأداتَين Formatter وEncrypter في مشروع Python.

    6. تصفُّح عيّنات الرموز البرمجية في الدليل الفرعي samples مرِّر الوسيطة --help عند تشغيل عيّنة لطباعة بيان الاستخدام مع المَعلمات المتوقّعة.

      لمساعدتك في البدء ببعض البيانات النموذجية، استخدِم الملف على samples/sampledata/audience_members_1.csv.

Node.js

  1. نزِّل الملف ads-datamanager-v1-nodejs.tar.gz واستخرِجه.
  2. انتقِل إلى دليل ads-datamanager-v1-nodejs.
  3. نفِّذ الأوامر التالية لتجميع المكتبة وحزمها في ملف .tgz لاستخدامه مع npm.

    npm install
    npm pack
    

    تنشئ الأوامر أرشيفًا باسم google-cloud-datamanager-0.1.0.tgz.

  4. في مشروع Node.js، حدِّد تبعية لمكتبة Data Manager API من خلال إضافة إدخال dependencies للمسار الكامل واسم الملف لملف google-cloud-datamanager-0.1.0.tgz.

PHP

  1. نزِّل الملف google-cloud-ads-datamanager-v1-php.tar.gz واستخرِجه.
  2. انتقِل إلى دليل google-cloud-ads-datamanager-v1-php.
  3. نفِّذ الأمر التالي لحلّ التبعيات الخاصة بالمكتبة:

    composer update --prefer-dist
    
  4. في ملف composer.json الخاص بمشروع PHP على المضيف نفسه، حدِّد اعتمادًا على مكتبة Data Manager API باتّباع الخطوات التالية:

    1. أضِف قسم repositories يشير إلى موقع الدليل google-cloud-ads-datamanager-v1-php.

      "repositories" : [
         {
            "type" : "path",
            "url" : "PATH_TO_CLIENT_LIBRARY"
         }
      ]
      
    2. عليك تحديد اعتماد على مكتبة Data Manager API.

      "require": {
         "googleads/data-manager": "^0.1.0"
      }
      
  5. (اختياري) الحصول على مكتبة الأدوات المساعدة وعيّنات الرموز البرمجية

    1. نزِّل الملف data-manager-php.tar.gz واستخرِجه.
    2. انتقِل إلى دليل data-manager-php.
    3. نفِّذ الأمر التالي لحلّ التبعيات الخاصة بالمكتبة:

      composer update --prefer-dist
      
    4. في ملف composer.json لمشروع PHP على المضيف نفسه، حدِّد تبعية لمكتبة الأدوات المساعدة باتّباع الخطوات التالية:

      1. أضِف إدخالاً في القسم repositories يشير إلى موقع الدليل data-manager-php.

        "repositories" : [
           {
              "type" : "path",
              "url" : "PATH_TO_UTILITY_LIBRARY"
           }
        ]
        
      2. عليك تعريف عنصر تابع لمكتبة الأدوات المساعدة.

        "require": {
           "googleads/data-manager-util": "@dev"
        }
        

      لتنسيق البيانات، استخدِم الأداة المساعدة Formatter في مشروع PHP.

    5. تصفُّح عيّنات الرموز البرمجية في الدليل الفرعي samples نفِّذ النماذج باتّباع الخطوات التالية:

      1. انتقِل إلى دليل samples.

      2. اضبط متغيّر البيئة DATA_MANAGER_PHP_LIB على المسار الذي استخرجت منه مكتبة البرامج.

        export DATA_MANAGER_PHP_LIB="PATH_TO_CLIENT_LIBRARY"
        
      3. نفِّذ الأمر التالي لحلّ التبعيات الخاصة بالمكتبة:

        composer update --prefer-dist
        
      4. نفِّذ النماذج مع إدخال أي وسيطات مطلوبة. مرِّر الوسيطة --help عند تشغيل نموذج لطباعة بيان الاستخدام مع المَعلمات المتوقّعة.

      لمساعدتك في البدء ببعض البيانات النموذجية، استخدِم الملف على samples/sampledata/audience_members_1.csv.