הגדרת גישה ל-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, או שיש לו תפקיד שכולל את ההרשאה הזו. לדוגמה, ההרשאות roles/owner ו-roles/serviceusage.serviceUsageAdmin כוללות את ההרשאה serviceusage.services.enable. כדי לבדוק את ההרשאות, אפשר לעיין במאמר בנושא הצגת הגישה הנוכחית.

הפעלת ה-API

אם עדיין לא עשיתם את זה, מפעילים את Data Manager API. לשם כך לוחצים על Enable the Data Manager API או פועלים לפי ההוראות.

הפעלת Data Manager API

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

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

אתם יכולים להשתמש בכל אחת משיטות האימות ב-Google, חוץ ממפתחות API. מומלץ לעיין במאמר בנושא בחירת שיטת האימות שמתאימה לתרחיש שלכם לדוגמה כדי להחליט איזו גישה מתאימה לתרחיש שלכם.

שתי שיטות נפוצות לאימות הן חשבונות משתמשים וחשבונות שירות:

  • חשבונות משתמשים: מייצגים אנשים שמנהלים אינטראקציה ישירה עם ממשקי ה-API והשירותים של Google.
  • חשבונות שירות: מייצגים אפליקציות, לא אנשים, בתור משתמשים. הן מאפשרות לאפליקציות שלכם לנהל אימות והרשאה. לדוגמה, אם אפליקציה צריכה לגשת למשאבים של Google Cloud.

השילוב יכול להשתמש ב-Application Default Credentials‏ (ADC) כדי למצוא באופן אוטומטי פרטי כניסה מהסביבה, כך שלא תצטרכו לשנות את קוד הלקוח כדי לבצע אימות.

בוחרים באפשרות חשבון משתמש או התחזות לחשבון שירות כדי להגדיר ADC:

כדי לבצע אימות באמצעות פרטי כניסה של חשבון משתמש:

  1. מגדירים את ההגדרות של Google Auth Platform בפרויקט.

    1. פותחים את הדף Branding במסוף Google Cloud.

    2. בוחרים את הפרויקט הרצוי.

    3. ממלאים את הטופס ולוחצים על יצירה.

  2. ההיקף של Data Manager API הוא היקף רגיש, ולכן צריך לבצע את השלבים הבאים:

    1. עוברים להגדרות Data Access (גישה לנתונים) של הפרויקט.

    2. לוחצים על הוספה או הסרה של היקפים.

    3. מסמנים את התיבה לצד Data Manager API (ה-API של המרכז לניהול נתונים) ברשימת ההיקפים ולוחצים על Update (עדכון).

    4. לוחצים על שמירה.

    5. עוברים אל קהל ב-Google Cloud Console ומעדכנים את סטטוס הפרסום ואת סוג המשתמש. מידע נוסף על ההגדרות האלה זמין במאמר בנושא ניהול קהלים של אפליקציות.

  3. לוחצים על Create OAuth2 client כדי ליצור לקוח OAuth2 בפרויקט, או פועלים לפי ההוראות ליצירת לקוח OAuth2 מסוג Desktop.

    יצירת לקוח OAuth2

    בשלב האחרון, לוחצים על הורדת הגדרות הלקוח ורושמים את מיקום ההורדה שבחרתם.

  4. מריצים את הפקודה הבאה כדי ליצור קובץ ADC מקומי. הפקודה הזו מפעילה תהליך אינטרנטי שבו מוצגת בקשה להתחבר לחשבון Google שבו אתם משתמשים עם ה-API.

    מחליפים את PATH_TO_CLIENT_JSON בשם של קובץ ה-JSON שהורדתם.

    gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform" \
  --client-id-file="PATH_TO_CLIENT_JSON"

  5. כדי לוודא שפרטי הכניסה מוגדרים בצורה נכונה, משתמשים בפקודה הבאה. אם הפקודה מסתיימת בלי שגיאות, היא מדפיסה אסימון גישה במסוף.

    gcloud auth application-default print-access-token

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

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

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

  • אם משתמשים בחשבון Google Ads או בחשבון של שותף נתונים, צריך לפעול לפי ההוראות כדי להוסיף את כתובת האימייל של המשתמש לחשבון.
  • אם אתם משתמשים בחשבון Display & Video 360, אתם צריכים לפעול לפי ההוראות כדי להוסיף את כתובת האימייל של המשתמש לחשבון.

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

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

REST

  1. צריך לעדכן את ה-placeholders בדוגמה הבאה, כמו OPERATING_ACCOUNT_PRODUCT,‏ OPERATING_ACCOUNT_ID ו-AUDIENCE_ID, עם הערכים של החשבון והיעד.
  2. מחליפים את PROJECT_ID במזהה של הפרויקט ב-Google Cloud.

  3. מעתיקים את הדוגמה לשורת הפקודה כדי לשלוח את הבקשה.

    מסירים את המאפיין linkedAccount של הרשומה ב-destinations אם לא ניגשים אל operatingAccount באמצעות קישור מוצר קיים.

    #!/bin/bash

# Uses gcloud to get an access token. If the Application Default
# Credentials aren't for a service account, the command that specifies
# --scopes fails. This sample falls back to the command without the
# --scopes argument.
DATA_MANAGER_ACCESS_TOKEN="$(gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/datamanager || \
  gcloud auth application-default print-access-token)"

# Fetches and prints the scope information for the access token. If you
# get scope-related errors when you send the request in the next step,
# verify that this output includes the Data Manager API scope:
#   https://www.googleapis.com/auth/datamanager
curl https://www.googleapis.com/oauth2/v1/tokeninfo?access_token="${DATA_MANAGER_ACCESS_TOKEN}"

# 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

‎.NET

  1. מורידים את הקובץ google-cloud-ads-datamanager-v1-csharp.tar.gz ופותחים אותו לתיקייה לא מכווצת.

  2. בפרויקט ‎ .NET, צריך להצהיר על ProjectReference תלות בספריית Data Manager API. מחליפים את PATH_TO_CLIENT_LIBRARY במיקום שבו חילצתם את הספרייה google-cloud-ads-datamanager-v1-csharp מ-google-cloud-ads-datamanager-v1-csharp.tar.gz.

    <ProjectReference Include="PATH_TO_CLIENT_LIBRARY\Google.Ads.DataManager.V1\Google.Ads.DataManager.V1.csproj" />

  3. אופציונלי. מקבלים את ספריית כלי העזר ודוגמאות הקוד.

    1. מורידים ומחלצים את הקובץ data-manager-dotnet.tar.gz.

    2. בפרויקט ‎ .NET, מצהירים על תלות בספריית כלי השירות ProjectReference. מחליפים את PATH_TO_UTILITY_LIBRARY במיקום שבו חילצתם את הספרייה data-manager-dotnet מתוך data-manager-dotnet.tar.gz.

      <ProjectReference Include="PATH_TO_UTILITY_LIBRARY\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />

    3. כדי לעצב נתונים, משתמשים בכלי Formatter בפרויקט ‎ .NET.

    4. דוגמאות קוד נמצאות בספריית המשנה samples.

      כדי להריץ את דוגמאות הקוד, צריך להגדיר את משתנה הסביבה DATA_MANAGER_DOTNET_LIB למיקום שבו חילצתם את הספרייה google-cloud-ads-datamanager-v1-csharp מתוך google-cloud-ads-datamanager-v1-csharp.tar.gz.

      export DATA_MANAGER_DOTNET_LIB="PATH_TO_CLIENT_LIBRARY"

      עוברים לספרייה samples ומשתמשים ב-dotnet run כדי לקבל את רשימת הדוגמאות הזמינות.

      dotnet run --framework net8.0

      כשמריצים מדגם כדי להדפיס הצהרת שימוש עם פרמטרים צפויים, צריך להעביר את הארגומנט --help.

      dotnet run --framework net8.0 -- ingest-audience-members --help

      כדי להתחיל לעבוד עם נתוני דוגמה, אפשר להשתמש בקובץ בכתובת samples/sampledata/audience_members_1.csv.

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. משכפלים את המאגר ב-GitHub.

      git clone https://github.com/googleads/data-manager-java.git

    2. מנווטים לספרייה data-manager-java.

    3. יוצרים ומפרסמים את ספריית כלי העזר במאגר 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 או ב-GitHub. כדי להריץ דוגמה משורת הפקודה, משתמשים במשימה run של Gradle.

      לדוגמה, הפקודה הבאה מריצה את הדוגמה 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.

השלבים הבאים