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

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

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

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

הכנת יעד

לפני ששולחים נתונים, צריך להכין את היעד שאליו רוצים לשלוח את הנתונים. הנה דוגמה ל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,

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

מסירים את כל הרווחים הלבנים בתחילת הטקסט, בסופו ובאמצעו.
ממירים את כתובת האימייל לאותיות קטנות.
מבצעים גיבוב של כתובת האימייל באמצעות האלגוריתם SHA-256.
מקודדים את בייטי הגיבוב באמצעות הקסדצימלי (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"
      }
    ]
  }
}

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

כדי ליצור את גוף הבקשה, משלבים את destinations ו-audienceMembers, מגדירים את השדה encoding ומוסיפים שדות בקשה אחרים שרוצים לכלול, כמו validateOnly ו-consent.

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

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

שליחת הבקשה

לוחצים על Open in API Explorer כדי לפתוח את API Explorer בכרטיסייה או בחלון חדשים.
בגוף הבקשה בכלי API Explorer, מחליפים כל מחרוזת שמתחילה ב-REPLACE_WITH, כמו REPLACE_WITH_OPERATING_ACCOUNT_TYPE, בערך הרלוונטי.
לוחצים על Execute (ביצוע) בחלק התחתון של הדף API Explorer ומשלימים את הנחיות ההרשאה כדי לשלוח את הבקשה.
מגדירים את validateOnly ל-true כדי לאמת את הבקשה בלי להחיל את השינויים. כשמוכנים להחיל את השינויים, מגדירים את validateOnly לערך false.

בקשה להטמעת נתונים

פתיחה ב-API Explorer

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

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

בקשה שמושלמת בהצלחה מחזירה תגובה עם אובייקט שמכיל 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 של המרכז לניהול נתונים שולח את חבר הקהל לכל היעדים בבקשה.

השלבים הבאים

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

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