Kitle üyelerini gönderme

Veri Yöneticisi API'si hakkında bilgi edinmek için bu hızlı başlangıç kılavuzunu inceleyebilirsiniz. Görmek istediğiniz hızlı başlangıç sürümünü seçin:

Bu hızlı başlangıç kılavuzunda aşağıdaki adımları tamamlayacaksınız:

  1. Kitle verilerini almak için bir Destination hazırlayın.
  2. Gönderilecek kitle verilerini hazırlayın.
  3. Kitle üyeleri için IngestionService isteği oluşturun.
  4. İsteği Google API Gezgini ile gönderin.
  5. Başarı ve hata yanıtlarını anlama

Hedef hazırlama

Veri gönderebilmek için verilerin gönderileceği hedefi hazırlamanız gerekir. Kullanabileceğiniz örnek bir Destination aşağıda verilmiştir. Farklı senaryolara yönelik hedef örnekleri için Hedefleri yapılandırma başlıklı makaleyi inceleyin.

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

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

      "productDestinationId": "AUDIENCE_ID"
    }
  • operatingAccount öğesini, kitle verilerini alacak hesabın hesap türü ve kimliği olarak ayarlayın.
  • OAuth kimlik bilgileriniz, alt hesaplarından biri operatingAccount olan bir Google Ads yönetici hesabına erişimi olan bir kullanıcıya aitse loginAccount değerini yönetici hesabının hesap türü ve kimliği olarak ayarlayın.
  • OAuth kimlik bilgileri, operatingAccount öğesine doğrudan erişimi olan bir kullanıcıya aitse loginAccount öğesini ayarlamanız gerekmez.

Kitle verilerini hazırlama

Virgülle ayrılmış bir dosyada aşağıdaki örnek verileri inceleyin. Dosyadaki her satır, kitlenin bir üyesine karşılık gelir ve her üyenin en fazla üç e-posta adresi olabilir.

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

E-posta adresleri aşağıdaki biçimlendirme ve karma oluşturma koşullarını karşılamalıdır:

  1. Baştaki, sondaki ve aradaki tüm boşlukları kaldırın.
  2. E-posta adresini küçük harfe dönüştürün.
  3. E-posta adresine SHA-256 algoritması kullanılarak karma oluşturma işlemi uygulayın.
  4. Karma baytlarını onaltılık (hex) veya Base64 kodlaması kullanarak kodlayın. Bu kılavuzdaki örneklerde onaltılık kodlama kullanılır.

Biçimlendirilmiş veriler:

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

Karma oluşturma ve kodlama işleminden sonraki veriler:

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

Giriş verilerinin ilk satırındaki dana@example.com ve danam@example.com'nin biçimlendirilmiş, karma uygulanmış ve kodlanmış e-posta adresleri için örnek bir AudienceMember aşağıda verilmiştir:

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

İstek gövdesini oluşturma

İstek gövdesini oluşturmak için destinations ve audienceMembers öğelerini birleştirin, encoding alanını ayarlayın ve validateOnly ile consent gibi eklemek istediğiniz diğer istek alanlarını ekleyin.

Müşteri Eşleştirme için kitle üyeleri gönderiyorsanız kullanıcının Müşteri Eşleştirme Hizmet Şartları'nı kabul edip etmediğini belirtmek için termsOfService değerini ayarlayın.

Bu kılavuzdaki örneklerde şifreleme kullanılmamaktadır. Ancak işleminize şifreleme eklemek için Kullanıcı verilerini şifreleme bölümündeki talimatları uygulayabilirsiniz.

İsteği gönderin.

  1. API Gezgini'ni yeni bir sekmede veya pencerede açmak için API Gezgini'nde aç'ı tıklayın.
  2. API Explorer'daki istek gövdesinde, REPLACE_WITH ile başlayan her dizeyi (ör. REPLACE_WITH_OPERATING_ACCOUNT_TYPE) ilgili değerle değiştirin.
  3. API Gezgini sayfasının alt kısmındaki Execute'u (Yürüt) tıklayın ve isteği göndermek için yetkilendirme istemlerini tamamlayın.
  4. Değişiklikleri uygulamadan isteği doğrulamak için validateOnly değerini true olarak ayarlayın. Değişiklikleri uygulamaya hazır olduğunuzda validateOnly seçeneğini false olarak ayarlayın.

Besleme isteği

API Gezgini'nde aç 
{
    "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
}

Başarılı yanıtlar

Başarılı bir istek, requestId içeren bir nesneyle yanıt döndürür.

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

İstek işlenirken her hedef için tanılama bilgilerini alabilmek amacıyla requestId döndürülenleri kaydedin.

Hata yanıtları

Başarısız bir istek, 400 Bad Request gibi bir hata yanıtı durum kodu ve hata ayrıntılarını içeren bir yanıtla sonuçlanır.

Örneğin, onaltılık kodlanmış değer yerine düz metin dizesi içeren bir emailAddress aşağıdaki yanıtı üretir:

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

Karma oluşturulmamış ve yalnızca on altılık olarak kodlanmış bir emailAddress, aşağıdaki yanıtı üretir:

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

Birden fazla hedef için etkinlik gönderme

Verileriniz farklı hedeflere yönelik kitle üyeleri içeriyorsa hedef referanslarını kullanarak bunları aynı istekte gönderebilirsiniz.

Örneğin, kullanıcı listesi kimliği 11112222 için bir kitle üyeniz ve kullanıcı listesi kimliği 77778888 için başka bir kitle üyeniz varsa her Destination öğesinin reference değerini ayarlayarak her iki kitle üyesini tek bir istekte gönderin. reference kullanıcı tarafından tanımlanır. Tek koşul, her Destination öğesinin benzersiz bir reference öğesine sahip olmasıdır. İstek için değiştirilen destinations listesi aşağıda verilmiştir:

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

Her bir AudienceMember öğesinin destination_references özelliğini, bir veya daha fazla belirli hedefe gönderecek şekilde ayarlayın. Örneğin, yalnızca ilk Destination için geçerli olan bir AudienceMember'nın destination_references listesinde yalnızca ilk Destination'nın reference yer alır:

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

destination_references alanı bir listedir. Bu nedenle, bir kitle üyesi için birden fazla hedef belirtebilirsiniz. Bir AudienceMember için destination_references ayarlamazsanız Data Manager API, kitle üyesini istekteki tüm hedeflere gönderir.

Sonraki adımlar

Önceki
Kitlelere genel bakış