Wysyłanie listy odbiorców

Dzięki temu krótkiemu wprowadzeniu możesz zapoznać się z interfejsem Data Manager API. Wybierz wersję przewodnika, którą chcesz wyświetlić:

W tym krótkim wprowadzeniu wykonasz te czynności:

  1. Przygotuj Destination do otrzymywania danych o odbiorcach.
  2. przygotować dane o odbiorcach do wysłania,
  3. Utwórz IngestionService prośbę o członków listy odbiorców.
  4. Wyślij żądanie za pomocą narzędzia Google APIs Explorer.
  5. Poznaj odpowiedzi o sukcesie i niepowodzeniu.

Przygotowywanie miejsca docelowego

Zanim wyślesz dane, musisz przygotować miejsce docelowe, do którego chcesz je przesłać. Oto przykładowy kod Destination, którego możesz użyć. Przykłady miejsc docelowych w różnych scenariuszach znajdziesz w artykule Konfigurowanie miejsc docelowych.

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

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

      "productDestinationId": "AUDIENCE_ID"
    }
  • Ustaw operatingAccount na typ konta i identyfikator konta, które będzie otrzymywać dane o odbiorcach.
  • Jeśli dane logowania OAuth dotyczą użytkownika, który ma dostęp do konta menedżera Google Ads, które ma operatingAccount jako jedno ze swoich subkont, ustaw loginAccount na typ konta i identyfikator konta menedżera.
  • Jeśli dane uwierzytelniające OAuth dotyczą użytkownika z bezpośrednim dostępem do operatingAccount, nie musisz ustawiać parametru loginAccount.

Przygotowywanie danych o odbiorcach

Rozważmy następujące przykładowe dane w pliku rozdzielonym przecinkami. Każdy wiersz w pliku odpowiada jednemu członkowi listy odbiorców, a każdy członek może mieć maksymalnie 3 adresy e-mail.

#,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,

Adresy e-mail muszą spełniać te wymagania dotyczące formatowania i szyfrowania:

  1. Usuń wszystkie spacje na początku, na końcu i w środku.
  2. przekonwertować adres e-mail na małe litery,
  3. Zahaszuj adres e-mail za pomocą algorytmu SHA-256.
  4. Zakoduj bajty skrótu za pomocą kodowania szesnastkowego (hex) lub Base64. W przykładach w tym przewodniku używamy kodowania szesnastkowego.

Oto sformatowane dane:

#,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,

A oto dane po zaszyfrowaniu i zakodowaniu:

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

Oto przykładowy parametr AudienceMember dla sformatowanych, zaszyfrowanych i zakodowanych adresów e-mail dana@example.com i danam@example.com z pierwszego wiersza danych wejściowych:

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

Tworzenie treści żądania

Aby utworzyć treść żądania, połącz pola destinations i audienceMembers, ustaw pole encoding i dodaj inne pola żądania, które chcesz uwzględnić, np. validateOnly i consent.

Jeśli wysyłasz listę odbiorców na potrzeby kierowania na listę klientów, ustaw wartość termsOfService, aby wskazać, czy użytkownik zaakceptował Warunki korzystania z kierowania na listę klientów.

Przykłady w tym przewodniku nie korzystają z szyfrowania, ale możesz dodać szyfrowanie do swojego procesu, postępując zgodnie z instrukcjami w artykule Szyfrowanie danych użytkownika.

Wysyłanie żądania

  1. Kliknij Otwórz w API Explorer, aby otworzyć API Explorer w nowej karcie lub oknie.
  2. W treści żądania w Eksploratorze interfejsu API zastąp każdy ciąg znaków zaczynający się od REPLACE_WITH, np. REPLACE_WITH_OPERATING_ACCOUNT_TYPE, odpowiednią wartością.
  3. U dołu strony narzędzia APIs Explorer kliknij Wykonaj i wykonaj instrukcje autoryzacji, aby wysłać żądanie.
  4. Ustaw wartość validateOnly na true, aby zweryfikować prośbę bez stosowania zmian. Gdy zechcesz zastosować zmiany, ustaw validateOnly na false.

Prośba o przetwarzanie

Otwórz w 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
}

Odpowiedzi o sukcesie

Pomyślne żądanie zwraca odpowiedź z obiektem zawierającym requestId.

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

Zapisz zwrócone requestId, aby móc pobrać diagnostykę w miarę przetwarzania każdego miejsca docelowego w żądaniu.

Odpowiedzi o błędach

Nieudane żądanie powoduje zwrócenie kodu stanu odpowiedzi o błędzie, np. 400 Bad Request, oraz odpowiedzi ze szczegółami błędu.

Na przykład emailAddress zawierający ciąg tekstowy zamiast wartości zakodowanej w formacie szesnastkowym generuje tę odpowiedź:

{
  "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, który nie jest haszowany i jest tylko zakodowany w formacie szesnastkowym, generuje następującą odpowiedź:

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

Wysyłanie zdarzeń do wielu miejsc docelowych

Jeśli dane zawierają członków odbiorców z różnych miejsc docelowych, możesz wysłać ich w tym samym żądaniu, używając odwołań do miejsc docelowych.

Jeśli na przykład masz odbiorcę na liście użytkowników o identyfikatorze 11112222 i innego odbiorcę na liście użytkowników o identyfikatorze 77778888, wyślij obu odbiorców w jednym żądaniu, ustawiając parametr reference każdego elementu Destination. Symbol reference jest definiowany przez użytkownika. Jedyny wymóg to unikalność symbolu reference w każdym przypadku.Destination Oto zmodyfikowana lista destinations w żądaniu:

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

Ustaw destination_references każdego AudienceMember, aby wysłać go do co najmniej jednego określonego miejsca docelowego. Na przykład ten AudienceMember dotyczy tylko pierwszego Destination, więc jego lista destination_references zawiera tylko reference pierwszego Destination:

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

Pole destination_references to lista, więc możesz określić wiele miejsc docelowych dla członka grupy odbiorców. Jeśli nie ustawisz parametru destination_references elementu AudienceMember, interfejs Data Manager API wyśle użytkownika do wszystkich miejsc docelowych w żądaniu.

Dalsze kroki

Wstecz
Odbiorcy ogółem