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

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

בוחרים את סוג תהליך ההגדרה שרוצים לבצע:

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

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

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

הפעלת ה-API

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

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

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

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

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

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

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

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

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

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

חשוב: כל אפליקציית Google Cloud שמשמשת להשגת פרטי כניסה של משתמשים להיקף של Data Manager API חייבת לעבור אימות של Google OAuth כדי שהמשתמשים שלה לא יראו מסך ממשק משתמש לא מאומת. לא נדרש אימות של Google OAuth לחשבונות שירות.
1. פותחים את הדף Branding במסוף Google Cloud.
2. בוחרים את הפרויקט הרצוי.
3. ממלאים את הטופס ולוחצים על יצירה.
ההיקף של Data Manager API הוא היקף רגיש, ולכן צריך לבצע את השלבים הבאים:
1. עוברים להגדרות גישה לנתונים של הפרויקט.
2. לוחצים על הוספה או הסרה של היקפים.
3. מסמנים את התיבה לצד Data Manager API (ה-API של המרכז לניהול נתונים) ברשימת ההיקפים ולוחצים על Update (עדכון).
4. לוחצים על שמירה.
5. עוברים אל קהל במסוף Google Cloud ומעדכנים את סטטוס הפרסום ואת סוג המשתמש. מידע נוסף על ההגדרות האלה זמין במאמר בנושא ניהול קהלים של אפליקציות.
לוחצים על Create OAuth2 client (יצירת לקוח OAuth2) כדי ליצור לקוח OAuth2 בפרויקט, או פועלים לפי ההוראות ליצירת לקוח OAuth2 למחשב.

אם לוחצים על Create OAuth2 client (יצירת לקוח OAuth2), בוחרים באפשרות Desktop app (אפליקציית מחשב) כשמוצגת ההנחיה Configure your OAuth client (הגדרת לקוח OAuth), כדי שתוכלו להשתמש בלקוח בשלבים הבאים.

יצירת לקוח OAuth2
בשלב האחרון, לוחצים על הורדת הגדרות הלקוח ורושמים את מיקום ההורדה שבחרתם.
מריצים את הפקודה הבאה כדי ליצור קובץ 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"
```
כדי לוודא שפרטי הכניסה מוגדרים בצורה נכונה, משתמשים בפקודה הבאה. אם הפקודה מסתיימת בלי שגיאות, היא מדפיסה אסימון גישה במסוף.
```
gcloud auth application-default print-access-token
```

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

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

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

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

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

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

REST

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

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

#!/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": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },
      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_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

התקנת ספריית הלקוח

פועלים לפי ההוראות במדריך התקנת ספריית לקוח ב-‎.NET כדי להוסיף תלות בספריית הלקוח בפרויקט.

אופציונלי: אפשר להוריד את ספריית כלי העזר ואת דוגמאות הקוד.

משכפלים את מאגר GitHub.

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

בפרויקט ‎ .NET, מצהירים על תלות בספריית כלי העזר ProjectReference. מחליפים את PATH_TO_UTILITY_LIBRARY במיקום שבו שיבטתם את מאגר data-manager-dotnet.
```
<ProjectReference Include="PATH_TO_UTILITY_LIBRARY\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />
```
כדי לעצב נתונים, משתמשים בכלי Formatter בפרויקט .NET.
אפשר לעיין בדוגמאות קוד בספריית המשנה samples או ב-GitHub.

עוברים לספרייה samples ומשתמשים ב-dotnet run כדי לקבל את רשימת הדוגמאות הזמינות.
```
dotnet run
```
כשמריצים דוגמה, מעבירים את הארגומנט --help כדי להדפיס הצהרת שימוש עם הפרמטרים הצפויים.
```
dotnet run -- ingest-audience-members --help
```
כדי לעזור לכם להתחיל עם נתוני דוגמה, אפשר להשתמש בקובץ בכתובת samples/sampledata/audience_members_1.csv.

Java

התקנת ספריית הלקוח

פועלים לפי ההוראות במדריך התקנת ספריית לקוח ב-Java כדי להוסיף תלות בספריית הלקוח בפרויקט.

אופציונלי: אפשר להוריד את ספריית כלי העזר ואת דוגמאות הקוד.

משכפלים את מאגר GitHub.

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

מנווטים לספרייה data-manager-java.
יוצרים את ספריית כלי העזר ומפרסמים אותה במאגר Maven המקומי.
```
./gradlew data-manager-util:install
```

בפרויקט Java, מצהירים על תלות בספריית כלי השירות.

‫Gradle:

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

‫Maven:

<dependency>
   <groupId>com.google.api-ads</groupId>
   <artifactId>data-manager-util</artifactId>
   <version>0.2.0</version>
</dependency>

כדי לעצב ולהצפין את הנתונים, משתמשים בכלי השירות UserDataFormatter ו-Encrypter בפרויקט Java.
אפשר לעיין בדוגמאות קוד בספריית המשנה data-manager-samples או ב-GitHub. כדי להריץ דוגמה משורת הפקודה, משתמשים במשימת Gradle‏ run.

לדוגמה, הפקודה הבאה מריצה את הדוגמה IngestAudienceMembers ומדפיסה הצהרת שימוש:
```
./gradlew data-manager-samples:run \
   --args='IngestAudienceMembers --help'
```
כדי לעזור לכם להתחיל עם נתוני דוגמה, אפשר להשתמש בקובץ בכתובת data-manager-samples/src/main/resources/sampledata/audience_members_1.csv.

Node.js

התקנת ספריית הלקוח

פועלים לפי ההוראות במדריך התקנת ספריית הלקוח Node.js כדי להוסיף תלות בספריית הלקוח @google-ads/datamanager בפרויקט.

אופציונלי: הורדה של ספריית כלי השירות ודוגמאות קוד.

משכפלים את מאגר GitHub.

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

מנווטים לספרייה data-manager-node.
מריצים את הפקודה הבאה כדי להתקין את יחסי התלות.
```
npm install
```
עוברים לספרייה util.
```
cd util
```
מריצים את הפקודה הבאה כדי לקמפל ולארוז את ספריית כלי השירות בקובץ .tgz לשימוש עם npm.
```
npm pack
```
הפקודה יוצרת ארכיון בשם google-ads-datamanager-util-0.2.0.tgz. חשוב לשים לב למיקום הקובץ כדי שתוכלו להשתמש בו בשלבים הבאים.
בפרויקט Node.js, מכריזים על תלות בספריית כלי השירות של Data Manager API על ידי הוספת רשומה dependencies לנתיב המלא ולשם הקובץ של הקובץ google-ads-datamanager-util-0.2.0.tgz.
```
{
   "dependencies": {
      ...
      "@google-ads/data-manager-util": "file:PATH_TO_UTILITY_LIBRARY/google-ads-datamanager-util-0.2.0.tgz",
      ...
   }
}
```
כדי לעצב את הנתונים, משתמשים בכלי UserDataFormatter בפרויקט Node.js.
אפשר לעיין בדוגמאות קוד בספריית המשנה samples או ב-GitHub. כדי להריץ את הדוגמאות:
1. מנווטים לספרייה data-manager-node.
2. מריצים את הדוגמאות ומעבירים את הארגומנטים הנדרשים. כשמריצים דוגמה, מעבירים את הארגומנט --help כדי להדפיס הצהרת שימוש עם פרמטרים צפויים.
  
  לדוגמה, הפקודה הבאה מריצה את הדוגמה ingest_audience_members ומדפיסה הצהרת שימוש:
```
npm run ingest-audience-members -w samples -- --help
```
כדי לעזור לכם להתחיל עם נתוני דוגמה, אפשר להשתמש בקובץ בכתובת samples/sampledata/audience_members_1.csv.

PHP

התקנת ספריית הלקוח

פועלים לפי ההוראות שבמדריך להתקנת ספריית הלקוח של PHP כדי להוסיף תלות בספריית הלקוח googleads/data-manager בפרויקט.

אופציונלי: הורדה של ספריית כלי השירות ודוגמאות קוד.

משכפלים את מאגר GitHub.

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

מנווטים לספרייה data-manager-php.
מריצים את הפקודה הבאה כדי לפתור את יחסי התלות של הספרייה:
```
composer update --prefer-dist
```
בקבץ 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.
אפשר לעיין בדוגמאות קוד בספריית המשנה samples או ב-GitHub. כדי להריץ את הדוגמאות:
1. מנווטים לספרייה samples.
2. מריצים את הפקודה הבאה כדי לפתור את יחסי התלות של הספרייה:
```
composer update --prefer-dist
```
3. מריצים את הדוגמאות ומעבירים את הארגומנטים הנדרשים. כשמריצים דוגמה, מעבירים את הארגומנט --help כדי להדפיס הצהרת שימוש עם פרמטרים צפויים.
כדי לעזור לכם להתחיל עם נתוני דוגמה, אפשר להשתמש בקובץ בכתובת samples/sampledata/audience_members_1.csv.

Python

התקנת ספריית הלקוח

פועלים לפי ההוראות שבמדריך להתקנת ספריית הלקוח של Python כדי להוסיף תלות בספריית הלקוח google-ads-datamanager בפרויקט.

אופציונלי: הורדה של ספריית כלי השירות ודוגמאות קוד.

משכפלים את מאגר GitHub.

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

מנווטים לספרייה data-manager-python.
כדי להתקין את ספריית כלי השירות בסביבת Python, מריצים את הפקודה הבאה:
```
pip install .
```
בפרויקט Python, מגדירים תלות בספריית כלי השירות. לדוגמה, אם משתמשים בקובץ requirements.txt בפרויקט, מוסיפים את השורה הבאה לקובץ:
```
google-ads-data-manager-util=0.2.0
```
כדי לעצב ולהצפין את הנתונים, משתמשים בכלי השירות Formatter ו-Encrypter בפרויקט Python.
אפשר לעיין בדוגמאות קוד בספריית המשנה samples או ב-GitHub. כדי להריץ דוגמאות, צריך להתקין את יחסי התלות הנדרשים:
```
pip install .[samples]
```
כשמריצים דוגמה, מעבירים את הארגומנט --help כדי להדפיס הצהרת שימוש עם הפרמטרים הצפויים.

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

Ruby

התקנת ספריית הלקוח

פועלים לפי ההוראות שבמדריך להתקנת ספריית הלקוח של Ruby כדי להוסיף תלות בספריית הלקוח בפרויקט.

הגדרת גישה ל-API קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

הפעלת ה-API

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

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

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

REST

‎.NET

התקנת ספריית הלקוח

אופציונלי: אפשר להוריד את ספריית כלי העזר ואת דוגמאות הקוד.

Java

התקנת ספריית הלקוח

אופציונלי: אפשר להוריד את ספריית כלי העזר ואת דוגמאות הקוד.

Node.js

התקנת ספריית הלקוח

אופציונלי: הורדה של ספריית כלי השירות ודוגמאות קוד.

PHP

התקנת ספריית הלקוח

אופציונלי: הורדה של ספריית כלי השירות ודוגמאות קוד.

Python

התקנת ספריית הלקוח

אופציונלי: הורדה של ספריית כלי השירות ודוגמאות קוד.

Ruby

התקנת ספריית הלקוח

השלבים הבאים

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