שליחת חברי הקהל

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

במדריך למתחילים הזה תבצעו את הפעולות הבאות:

  1. מכינים Destination לקבלת נתוני קהל.
  2. הכנת נתוני קהל לשליחה.
  3. בונים בקשת IngestionService לחברי הקהל.
  4. שולחים את הבקשה באמצעות Google APIs Explorer.
  5. הסבר על תגובות הצלחה וכישלון.

הכנת יעד

לפני ששולחים נתונים, צריך להכין את היעד שאליו רוצים לשלוח את הנתונים. הנה דוגמה ל-Destination שאפשר להשתמש בה. במאמר הגדרת יעדים יש דוגמאות ליעדים בתרחישים שונים.

    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }
  • מגדירים את operatingAccount לסוג החשבון ולמזהה של החשבון שיקבל את נתוני הקהל.
  • אם פרטי הכניסה ל-OAuth הם של משתמש עם גישה לחשבון ניהול ב-Google Ads, שחשבון operatingAccount הוא אחד מהחשבונות המשניים שלו, צריך להגדיר את loginAccount לסוג החשבון ולמזהה של חשבון הניהול.
  • אם פרטי הכניסה ל-OAuth הם של משתמש עם גישה ישירה אל operatingAccount, לא צריך להגדיר את loginAccount.

הכנת נתוני קהל

הנה דוגמה לנתונים בקובץ מופרד בפסיקים. כל שורה בקובץ מייצגת חבר אחד בקהל, ולכל חבר יש עד שלוש כתובות אימייל.

#,email_1,email_2,email_3
1,dana@example.com,DanaM@example.com,
2,ALEXJ@example.com, AlexJ@cymbalgroup.com,alexj@altostrat.com
3,quinn@CYMBALGROUP.com,baklavainthebalkans@gmail.com  ,
4,rosario@example.org,cloudySanFrancisco@GMAIL.com,

כתובות אימייל צריכות לעמוד בדרישות הפורמט והגיבוב הבאות:

  1. מסירים את כל הרווחים הלבנים בתחילת הטקסט, בסופו ובאמצעו.
  2. ממירים את כתובת האימייל לאותיות קטנות.
  3. מבצעים גיבוב של כתובת האימייל באמצעות האלגוריתם SHA-256.
  4. מקודדים את בייטי הגיבוב באמצעות הקסדצימלי (hex) או קידוד Base64. הדוגמאות במדריך הזה משתמשות בקידוד הקסדצימלי.

אלה הנתונים בפורמט:

#,email_1,email_2,email_3
1,dana@example.com,danam@example.com,
2,alexj@example.com,alexj@cymbalgroup.com,alexj@altostrat.com
3,quinn@cymbalgroup.com,baklavainthebalkans@gmail.com,
4,rosario@example.org,cloudysanfrancisco@gmail.com,

אלה הנתונים אחרי הגיבוב והקידוד:

#,email_1,email_2,email_3
1,07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3,1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7
2,2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3,54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51,e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478
3,05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0,f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5
4,83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f,223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4

הנה דוגמה ל-AudienceMember של כתובות האימייל dana@example.com ו-danam@example.com מהשורה הראשונה של נתוני הקלט, אחרי שהן עברו עיצוב, גיבוב וקידוד:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ]
  }
}

בניית גוף הבקשה

משלבים את Destination ו-userData בגוף הבקשה:

{
  "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
}
  1. מעדכנים את ערכי ה-placeholder בגוף הבקשה, כמו OPERATING_ACCOUNT_TYPE,‏ OPERATING_ACCOUNT_ID ו-AUDIENCE_ID, עם הערכים של החשבון ויעד ההפניה.
  2. מגדירים את validateOnly לערך true כדי לאמת את הבקשה בלי להחיל את השינויים. כשמוכנים להחיל את השינויים, מגדירים את validateOnly לערך false.
  3. מגדירים את הערך termsOfService כדי לציין שהמשתמש אישר את התנאים וההגבלות של התאמה ללקוחות.
  4. שימו לב: הבקשה הזו מציינת שהגישה ל-consent ניתנה, ולא נעשה שימוש בהצפנה.

שליחת הבקשה

  1. מעתיקים את גוף הבקשה באמצעות לחצן ההעתקה בפינה השמאלית העליונה של הדוגמה.
  2. בסרגל הכלים, לוחצים על הלחצן API.
  3. מדביקים את גוף הבקשה שהועתק בתיבה גוף הבקשה.
  4. לוחצים על הלחצן Execute (הפעלה), פועלים לפי ההנחיות לאישור הגישה ובודקים את התגובה.

תגובות שבוצעו בהצלחה

אם הבקשה מצליחה, מוחזרת תגובה עם אובייקט שמכיל requestId.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a"
}

כדאי לתעד את requestId שמוחזר כדי שתוכלו לאחזר אבחון כשכל יעד בבקשה יעבור עיבוד.

תגובות שגיאה

בקשה שנכשלה מניבה קוד סטטוס של תגובה עם שגיאה, כמו 400 Bad Request, ותגובה עם פרטי השגיאה.

לדוגמה, אם emailAddress מכיל מחרוזת של טקסט פשוט במקום ערך מקודד הקסדצימלי, התגובה הבאה תתקבל:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0].user_data.user_identifiers",
            "description": "Email is not hex encoded.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

אם מחרוזת emailAddress לא עוברת גיבוב אלא רק קידוד הקסדצימלי, התשובה שמתקבלת היא:

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "audience_members.audience_members[0]",
            "reason": "INVALID_SHA256_FORMAT"
          }
        ]
      }
    ]
  }
}

שליחת אירועים למספר יעדים

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

לדוגמה, אם יש לכם חבר בקהל עם מזהה רשימת משתמשים 11112222 וחבר נוסף בקהל עם מזהה רשימת משתמשים 77778888, אתם יכולים לשלוח את שני החברים בקהל בבקשה אחת על ידי הגדרת הפרמטר reference של כל אחד מהפרמטרים Destination. הערך של reference מוגדר על ידי המשתמש – הדרישה היחידה היא שלכל reference יהיה reference ייחודי.Destination זו רשימת destinations ששונתה עבור הבקשה:

  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_2_TYPE",
        "accountId": "OPERATING_ACCOUNT_2_ID"
      },

      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_2_TYPE",
        "accountId": "LOGIN_ACCOUNT_2_ID"
      },

      "productDestinationId": "77778888",
      "reference": "audience_2"
    }
  ]

מגדירים את destination_references של כל AudienceMember כדי לשלוח אותו ליעד ספציפי אחד או יותר. לדוגמה, הנה AudienceMember שרלוונטי רק ל-Destination הראשון, ולכן רשימת ה-destination_references שלו מכילה רק את reference של Destination הראשון:

{
  "userData": {
    "userIdentifiers": [
      {
        "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
      },
      {
        "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
      }
    ],
  }
  "destinationReferences": [
    "audience_1"
  ]
}

השדה destination_references הוא רשימה, ולכן אפשר לציין כמה יעדים לחבר בקהל. אם לא מגדירים את destination_references של AudienceMember, ה-API של המרכז לניהול נתונים שולח את חבר הקהל לכל היעדים בבקשה.

השלבים הבאים

הקודם
סקירה כללית על קהלים