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

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

מפרסם שותף נתונים

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

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

הכנת יעד

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

    {
      "operatingAccount": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "AUDIENCE_ID"
    }

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

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

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

#,email_1,email_2,email_3
1,[e-mail],[e-mail],
2,[e-mail], [e-mail],[e-mail]
3,[e-mail],[e-mail]  ,
4,[e-mail],[e-mail],

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

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

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

#,email_1,email_2,email_3
1,[e-mail],[e-mail],
2,[e-mail],[e-mail],[e-mail]
3,[e-mail],[e-mail],
4,[e-mail],[e-mail],

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

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

הנה דוגמה ל-AudienceMember של כתובות אימייל בפורמט, שעברו גיבוב וקידוד של [e-mail] ו[e-mail] מהשורה הראשונה של נתוני הקלט:

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

יצירת גוף הבקשה

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

{
  "destinations": [
    {
      "operatingAccount": {
        "product": "OPERATING_ACCOUNT_PRODUCT",
        "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_PRODUCT,‏ 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"
}

תגובות שמעידות על כשל

בקשה שנכשלה מניבה קוד סטטוס של תגובה עם שגיאה, כמו 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"
          }
        ]
      }
    ]
  }
}

השלבים הבאים

• מגדירים אימות ומכינים את הסביבה באמצעות ספריית לקוח.
• מידע נוסף על הדרישות לגבי פורמט, גיבוב (hashing) וקידוד לכל סוג נתונים.
• איך מצפינים נתוני משתמשים
• שיטות מומלצות
• מידע נוסף על מגבלות ומכסות