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

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

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

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

הכנת יעד

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

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

      "productDestinationId": "AUDIENCE_ID"
    }

  • מגדירים את operatingAccount לסוג החשבון ולמזהה של החשבון שיקבל את נתוני הקהל.

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

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

#,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. מבצעים גיבוב (hash) של כתובת האימייל באמצעות האלגוריתם 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"
      },

      "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, ותגובה עם פרטי השגיאה.

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

{
  "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"
          }
        ]
      }
    ]
  }
}

מחרוזת email_address שלא עוברת גיבוב ומקודדת רק בפורמט הקסדצימלי מפיקה את התגובה הבאה:

{
  "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": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_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 של המרכז לניהול נתונים שולח את חבר הקהל לכל היעדים בבקשה.

השלבים הבאים

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