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:

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

      "productDestinationId": "AUDIENCE_ID"
    }

  • operatingAccount öğesini, kitle verilerini alacak hesabın hesap türü ve kimliği olarak ayarlayın.

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övdesi için Destination ve userData değerlerini birleştirin:

{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "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. Gövdedeki yer tutucuları (ör. OPERATING_ACCOUNT_TYPE, OPERATING_ACCOUNT_ID ve AUDIENCE_ID) hesabınız ve hedefiniz için uygun değerlerle güncelleyin.
  2. 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.
  3. Kullanıcının Müşteri Eşleştirme Hizmet Şartları'nı kabul ettiğini belirtmek için termsOfService değerini ayarlayın.
  4. Bu isteğin consent izninin verildiğini gösterdiğini ve şifreleme kullanılmadığını unutmayın.

İsteği gönderin

  1. Örneğin sağ üst kısmındaki kopyalama düğmesini kullanarak istek gövdesini kopyalayın.
  2. Araç çubuğunda API düğmesini tıklayın.
  3. Kopyalanan istek gövdesini İstek gövdesi kutusuna yapıştırın.
  4. Execute (Çalıştır) düğmesini tıklayın, yetkilendirme istemlerini tamamlayın ve yanıtı inceleyin.

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 email_address 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 email_address 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": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_ID"
      },

      "productDestinationId": "11112222",
      "reference": "audience_1"
    },
    {
      "operatingAccount": {
        "accountType": "GOOGLE_ADS",
        "accountId": "OPERATING_ACCOUNT_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, burada yalnızca ilk Destination için olan bir AudienceMember var. Bu nedenle, destination_references listesinde yalnızca ilk Destination'nin reference yer alıyor:

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

destination_references alanı bir liste olduğundan, bir kitle üyesi için birden fazla hedef belirtebilirsiniz. Bir AudienceMember için destination_references ayarlamazsanız Veri Yöneticisi API'si, kitle üyesini istekteki tüm hedeflere gönderir.

Sonraki adımlar

Önceki
Kitlelere genel bakış