Krótkie wprowadzenie

Aby zapoznać się z interfejsem Data Manager API, możesz przejść przez to krótkie wprowadzenie. Wybierz wersję samouczka, którą chcesz wyświetlić:

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

  1. Przygotuj Destination, aby otrzymywać dane o odbiorcach.
  2. Przygotuj dane odbiorców do wysłania.
  3. Utwórz żądanie IngestionService.
  4. Wyślij żądanie za pomocą narzędzia Google APIs Explorer.
  5. Poznaj odpowiedzi na powodzenie i niepowodzenie.

Przygotowanie miejsca docelowego

Zanim wyślesz dane, musisz przygotować miejsce docelowe. Oto przykładowa Destination:

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

      "productDestinationId": "AUDIENCE_ID"
    }

  • Ustaw parametr operatingAccount na nazwę usługi i identyfikator konta, które mają otrzymywać dane o odbiorcach.

Przygotowywanie danych odbiorców

Rozważ te przykładowe dane w pliku rozdzielonym przecinkami. Każdy wiersz w pliku odpowiada jednemu odbiorcy, a każdy odbiorca ma 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 zaszyfrowania:

  1. Usuń wszystkie spacje na początku, na końcu i pomiędzy znakami.
  2. Konwertuj adres e-mail na małe litery.
  3. Zaszyfruj adres e-mail za pomocą algorytmu SHA-256.
  4. Zakoduj bajty szyfrowania za pomocą kodowania szesnastkowego (szesnastkowego) lub kodowania Base64. Przykłady w tym przewodniku używają 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 tak wyglądają 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ład 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

Połącz Destination i userData w treści żądania:

{
  "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. Zaktualizuj zmienne w treści, takie jak OPERATING_ACCOUNT_PRODUCT, OPERATING_ACCOUNT_ID i AUDIENCE_ID, wartościami dla swojego konta i miejsca docelowego.
  2. Aby zweryfikować żądanie bez stosowania zmian, ustaw wartość validateOnly na true. Gdy chcesz zastosować zmiany, ustaw wartość validateOnly na false.
  3. Ustaw wartość termsOfService, aby wskazać, że użytkownik zaakceptował Warunki korzystania z usługi Google Customer Match.
  4. Ta prośba wskazuje, że consent jest przyznana i nie używa szyfrowania.

Wysyłanie żądania

  1. Skopiuj treść prośby, klikając przycisk kopiowania w prawym górnym rogu przykładu.
  2. Otwórz stronę audienceMembers.ingest.
  3. Kliknij przycisk API po prawej stronie, a następnie w rozwiniętej sekcji kliknij przycisk Wypróbuj.
  4. Wklej skopiowany tekst żądania do pola Treść żądania.
  5. Kliknij przycisk Wykonaj, wypełnij prośby o autoryzację i sprawdź odpowiedź.

Odpowiedzi na pytania dotyczące powodzenia

Żądanie zakończone pomyślnie zwraca odpowiedź z obiektem zawierającym requestId.

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

Odpowiedzi na błąd

Nieudane żądanie powoduje zwrócenie kodu stanu odpowiedzi zawierającego błąd, np. 400 Bad Request, oraz odpowiedzi z szczegółami błędu.

Na przykład email_address zawierający ciąg tekstowy zamiast wartości zakodowanej szesnastkowo powoduje wyświetlenie tej odpowiedzi:

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

Wartość email_address, która nie jest zaszyfrowana i ma tylko kodowanie szesnastkowe, powoduje 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"
          }
        ]
      }
    ]
  }
}

Dalsze kroki