מדריך למתחילים

מומלץ לקרוא את המדריך למתחילים הזה כדי להכיר את 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,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": {
        "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 כדי לציין שהמשתמש אישר את התנאים וההגבלות של Customer Match.
  4. שימו לב שהבקשה הזו מציינת שהרשאה consent ניתנה, ולא נעשה בה שימוש בהצפנה.

שליחת הבקשה

  1. מעתיקים את גוף הבקשה באמצעות לחצן ההעתקה בפינה השמאלית העליונה של הדוגמה.
  2. עוברים לדף audienceMembers.ingest.
  3. לוחצים על הלחצן API בצד שמאל, ואז על הלחצן לניסיון בקטע המורחב.
  4. מדביקים את גוף הבקשה שהועתק בתיבה Request body.
  5. לוחצים על הלחצן 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"
          }
        ]
      }
    ]
  }
}

השלבים הבאים