הגדרת גישה ל-API

כך מגדירים גישה ל-Data Manager API באמצעות SDK או REST.

דרישות מוקדמות

לפני שמשתמשים ב-Data API, צריך לוודא שיש לכם את הדברים הבאים:

  1. פרויקט ב-Google Cloud.
  2. חשבון Google שעומד בשני הקריטריונים הבאים:
    1. קיבלתם גישה ל-Data Manager API אחרי שמילאתם את טופס ההבעת עניין ב-Data Manager API. אם אתם רואים את דף פרטי מוצר ה-API, יש לכם גישה.
    2. יש לו את ההרשאה serviceusage.services.enable בפרויקט ב-Google Cloud, או שיש לו תפקיד שכולל את ההרשאה הזו. לדוגמה, ההרשאה serviceusage.services.enable כלולה גם ב-roles/owner וגם ב-roles/serviceusage.serviceUsageAdmin. כדי לבדוק את ההרשאות, אפשר לעיין במאמר בנושא הצגת הגישה הנוכחית.

הפעלת ה-API

אם עדיין לא עשיתם זאת, מפעילים את Data Manager API.

אם אתם לא מוצאים את Data Manager API, כדאי לוודא שחשבון Google שלכם עומד בדרישות המוקדמות.

מגדירים אימות

בוחרים שיטת אימות ומגדירים אותה. מומלץ להגדיר את Application Default Credentials כדי למצוא באופן אוטומטי את פרטי הכניסה מהסביבה. ה-API הזה לא משתמש במפתחות API.

ההיקף https://www.googleapis.com/auth/datamanager נדרש לכל פרטי כניסה שמשמשים עם Data Manager API. דוגמה לשימוש בהיקפים מופיעה במסמכי התיעוד של הפקודה gcloud auth application-default login.

למידע נוסף על אימות ופרטי כניסה לאפליקציה, ראו שיטות אימות ב-Google והסבר על Application Default Credentials.

הגדרת גישה לחשבון הפעלה

נותנים לכתובת האימייל שמשויכת למשתמש או לחשבון השירות גישה אל Destination.

הגדרת ה-SDK לשפת התכנות

במחשב המקומי, מתקינים את ה-SDK הרצוי:

REST

  1. צריך לעדכן את ה-placeholders בדוגמה הבאה, כמו 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. אופציונלי. מקבלים את ספריית כלי העזר ודוגמאות הקוד.

    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. אופציונלי. מקבלים את ספריית כלי העזר ודוגמאות הקוד.

    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.