API de plateforme numérique - Service de segment batch

Le service Batch Segment vous permet de charger des audiences sur la plateforme Xandr via une infrastructure de chargement par lots/en bloc. Ces données peuvent être utilisées conjointement avec les données des acheteurs ou des vendeurs à des fins de ciblage de campagne ou de gestion du rendement. Toutes les données envoyées via le service de segment batch sont ajoutées aux données de segment existantes déjà présentes dans notre système.

Les fonctionnalités sont les suivantes :

Possibilité de charger des fichiers compressés
Vérification des erreurs des données de segment
Format de fichier d’entrée configurable
Confirmation d’un chargement réussi
Commentaires sur le status de traitement global
Association de segments aux utilisateurs, quel que soit leur emplacement
Volume de données maximal élevé

Pour des résultats optimaux, il est fortement recommandé d’implémenter les meilleures pratiques dans Les meilleures pratiques du service de segment de lots.

Remarque

Le service Batch Segment nécessite une configuration avant de l’utiliser. Consultez Batch Segment Service - Configuration pour savoir comment le configurer pour votre siège.

Importante

Gzip est la seule méthode de compression de fichier prise en charge par ce service.

Ajouter un fichier de segment pour le traitement

L’ajout de votre fichier de segment au système est un processus en trois étapes. Tout d’abord, demandez un numéro d’identification du travail et une URL de chargement. Ensuite, chargez votre fichier vers l’URL de chargement attribuée. Troisièmement, case activée le status de traitement du travail. Notez que pour l’instant, les fichiers sont limités à au maximum 1 800 segments sur une ligne individuelle. Si vous avez plus de 1 800 segments pour un utilisateur, vous devez diviser cette ligne en plusieurs lignes.

Étape 1. Demander une URL de chargement et un ID de travail
Étape 2. Publier le fichier dans l’URL de chargement
Étape 3. Vérifier la status du travail

Étape 1. Demander une URL de chargement et un ID de travail

Chaque fichier de données de segment chargé doit être associé à un ID de travail particulier. Cet ID est utilisé pour créer l’URL de chargement et suivre les status de traitement du fichier. La première étape consiste à envoyer une requête vide POST au service.

Remarque

Ce service fonctionne à la fois api.appnexus.com pour et api.adnxs.com. Il est disponible pour les connexions de soumissionnaire et de console.

$ curl -b cookies -X POST "https://api.appnexus.com/batch-segment?member_id=456"

{
 "response": {
  "id": 123,
  "status": "OK",
  "batch_segment_upload_job": {
   "job_id": "JFY8l6iMOFAFJIWCMPcy39MCt3Yleo1337618549",
   "id": 123,
   "member_id": 456,
   "last_modified": "2012-05-21 16:42:29",
   "upload_url": "https://01.data-api.prod.adnxs.net/segment-upload/JFY8l6iMOFAFJIWCMPcy39MCt3Yleo1337618549"
  },
  "start_element": 0,
  "count": 1,
  "num_elements": 100,
  "dbg_info": {
  ...
  }
 }
}

Étape 2. Publier le fichier dans l’URL de chargement

L’URL de chargement du fichier est indiquée dans la réponse JSON à l’étape 1 dans le champ upload_url. Vous devez POST votre fichier de segment à cette URL pour le traitement. Vous recevez un objet JSON qui vous indique si le chargement a réussi. Ne codez pas en dur l’URL de chargement dans votre application ; veillez à le récupérer dynamiquement à partir du upload_url champ.

Remarque

Vous devez commencer votre chargement vers l’URL de chargement donnée dans les cinq minutes, et une seule URL est valide à un moment donné. Si vous attendez plus de cinq minutes pour démarrer votre chargement, vous devez demander une nouvelle URL.
Nous vous recommandons de ne pas dépasser un chargement par minute. Si vous avez plus de 200 travaux en attente de traitement à un moment donné, il vous sera interdit de charger des travaux supplémentaires.
Votre fichier de segment ne doit pas dépasser 0,5 Go.

Avertissement

Pour que le fichier soit chargé correctement, vous devez spécifier le type MIME dans l’en-tête HTTP en tant que « Content-Type : application/octet-stream ». N’utilisez pas « Content-Type : application/x-www-form-urlencode » (-d ou --data flags in curl). L’utilisation d’un type MIME incorrect empêche le fichier d’être traité par le service de segment par lots de l’API.

Votre fichier doit être conforme au jeu de caractères Latin1.

$ curl -v -H 'Content-Type:application/octet-stream' -b cookies -X POST --data-binary @segment_file "https://01.data-api.prod.adnxs.net/segment-upload/JFY8l6iMOFAFJIWCMPcy39MCt3Yleo1337618549"

* About to connect() to 01.data-api.prod.adnxs.net port 80
*   Trying 64.210.62.71... connected
* Connected to 01.data-api.prod.adnxs.net (64.210.62.71) port 80
> POST /segment-upload/FkmOY7oL2Qy2aCE7NrhE1BHVoJA0wi1337697712 HTTP/1.1
> User-Agent: curl/7.15.5 (x86_64-redhat-linux-gnu) libcurl/7.15.5 OpenSSL/0.9.8b zlib/1.2.3 libidn/0.6.5
> Host: 01.data-api.prod.adnxs.net
> Accept: */*
> Content-type:application/octet-stream
> Content-Length: 116
>
> 7652266028043224430;5848:0,5849:1440,5850:14404013681496264948522;5013:0,5014:15508802117132500293405;5851:0,5847:-1HTTP/1.1 200 OK
< Date: Tue, 22 May 2012 14:48:02 GMT
< Content-Type: application/json
< Transfer-Encoding: chunked
< Server: Jetty(7.6.2.v20120308)
* Connection #0 to host 01.data-api.prod.adnxs.net left intact
* Closing connection #0
{"response":{"segment_upload":{"job_id":"FkmOY7oL2Qy2aCE7NrhE1BHVoJA0wi1337697712"},"status":"OK"}}

Exemple d’URL de chargement SSL

curl -b cookie -c cookie -X POST -s -d '' "https://api.appnexus.com/batch-segment?member_id=958"

"batch_segment_upload_job": {
      "id": 14841671,
      "job_id": "qGQhSZ1qvd2hSsJ9svTz32qgxq7z5b1439315424",
      "member_id": 958,
      "last_modified": "2015-08-11 17:50:24",
      "upload_url": "https://data-api-gslb.adnxs.net/segment-upload/qGQhSZ1qvd2hSsJ9svTz32qgxq7z5b1439315424"
    }

Étape 3. Vérifier la status du travail

Enfin, case activée le status de traitement en envoyant une GET requête. La réponse JSON contient des informations telles que la durée de traitement du fichier et le nombre d’erreurs, le cas échéant. Notez que vous devez attendre avant phase="completed" d’examiner les champs de résultats, tels que num_valid. Pour plus d’informations, consultez Champs JSON ci-dessous.

Remarque

Selon le contrat SLA Xandr, attendez jusqu’à 24 heures pour que le fichier soit traité.
Si vous êtes un fournisseur de données utilisant l’API Impbus, notez que le batch_segment_upload_job champ est un tableau contenant un seul objet, par exemple : {"batch_segment_upload_job":[{"phase":"completed" }]}

$ curl -b cookies "https://api.appnexus.com/batch-segment?member_id=456&job_id=JFY8l6iMOFAFJIWCMPcy39MCt3Yleo1337618549"

{
 "response": {
  "start_element": 0,
  "count": 1,
  "batch_segment_upload_job": {
   "phase": "completed",
   "start_time": "2012-05-21 20:04:35",
   "uploaded_time": "2012-05-21 20:04:41",
   "validated_time": "2012-05-21 20:07:24",
   "completed_time": "2012-05-21 20:08:24",
   "error_code": null,
   "time_to_process": "2.69",
   "percent_complete": 100,
   "num_valid": 200000,
   "num_valid_user":100000
   "num_invalid_format": 0,
   "num_invalid_user": 0,
   "num_invalid_segment": 0,
   "num_unauth_segment": 1,
   "num_past_expiration": 0,
   "num_inactive_segment": 0,
   "num_other_error": 0,
   "error_log_lines": " \n\nnum_unauth_segment-4013681496264948522;5013:0,5014:1550",
   "segment_log_lines": "\n5010:100000\n5011:50000\n5012:50000",
   "id": 88,
   "job_id": "4tGhzv2PojNGQpq0MYaoaOa70cuF061337630675",
   "member_id": 456,
   "created_on": "2012-05-21 20:04:35",
   "last_modified": "2012-05-21 20:08:24"
  },
  "dbg_info": {
  ...
  },
  "status": "OK",
  "num_elements": 100
 }
}

Erreurs de chargement possibles

Tentative de chargement d’un fichier supérieur à 0,5 Go

{"response":{"status":"ERROR","error_code":"FILESIZE_LIMIT_EXCEEDED","errors":["Member exceeds maximum byte size allowed for a file"]}}

Code d’erreur dans le travail de chargement de segment de lot

""batch_segment_upload_job": {
      "phase": "error",
      "start_time": "2015-08-13 18:40:32",
      "uploaded_time": null,
      "validated_time": null,
      "completed_time": null,
      "error_code": "uploading-error",
      "time_to_process": "0.00",
      "percent_complete": 0,
      "num_valid": 0,
      "num_invalid_format": 0,
      "num_valid_user": 0,
      "num_invalid_user": 0,
      "num_invalid_segment": 0,
      "num_invalid_timestamp": 0,
      "num_unauth_segment": 0,
      "num_past_expiration": 0,
      "num_inactive_segment": 0,
      "num_other_error": 0,
      "error_log_lines": null,
      "segment_log_lines": null,
      "id": 11661553,
      "job_id": "Pm3oCUf5CSVKIOt4mAqOzdt6K3qInj1431542432",
      "member_id": 958,
      "created_on": "2015-05-13 18:40:32",
      "last_modified": "2015-05-13 18:40:33"
    }

Voici les erreurs qui peuvent se produire dans les cas suivants :

Vous avez annulé le chargement.
La phase de chargement dépasse 90 minutes.
Vous avez atteint l’une de ses quatre limites de chargement (octets quotidiens, octets horaires ou limite de lignes horaires).

Tentative de dépassement de la limite quotidienne de chargement d’octets

 {"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Member exceeds maximum allowed bytes per day"]}}

Tentative de dépassement de la limite de chargement d’octets horaire

{"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Member exceeds maximum allowed number of lines per hour"]}}

Tentative de dépassement de la limite de chargement de lignes quotidiennes

{"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Member exceeds maximum allowed number of lines per day"]}}

Tentative de dépassement de la limite de chargement de lignes horaires

{"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Member exceeds maximum allowed lines per hour"]}}

Dépassement de la durée maximale de chargement

{"response":{"status":"ERROR","error_code":"RATE_LIMIT_EXCEEDED","errors":["Maximum upload time exceeded"]}}

Erreurs de traitement possibles

Format non valide

Si la valeur du num_invalid_format champ est supérieure "0"à , case activée les valeurs du error_log_lines champ.

Dans l’exemple ci-dessous, le num_invalid_format champ affiche la valeur "1", avec les détails fournis dans le error_log_lines champ.

Dans le error_log_lines champ :

num_invalid_format indique qu’un problème s’est produit lors de l’analyse d’une ligne dans le fichier chargé.
"failed with an illegal number of fields" indique que le nombre de champs d’un segment_fields bloc ne correspondait pas à ce qui a été défini dans la configuration du segment de lot. Pour plus d’informations, consultez Batch Segment Service - Configuration.

Dans ce cas, la configuration s’attend à ce que trois champs soient définis dans le bloc : SEG_ID, VALUEet EXPIRATION, mais l’analyseur n’a trouvé que deux champs - SEG_ID et , affichant VALUEainsi une erreur.

`num_invalid_format` et `error_log_lines` exemple

"batch_segment_upload_job": {
phase": "completed",
"error_code": null,
"time_to_process": "0.01",
"percent_complete": 100,
"num_valid": 0,
"num_invalid_format": 1,
"num_valid_user": 0,
"num_invalid_user": 0,
"num_invalid_segment": 0,
"num_invalid_timestamp": 0,
"num_unauth_segment": 0,
"num_past_expiration": 0,
"num_inactive_segment": 0,
"num_other_error": 0,
"error_log_lines": "num_invalid_format-WINDOWSADID-USER-ID;SEG_ID:VALUE~9 failed with an illegal number of fields",
"segment_log_lines": null,
"start_time": "2015-08-13 18:40:32",
"uploaded_time": "2015-08-13 18:42:32",
"validated_time": "2015-08-13 18:42:32",
"completed_time": "2015-08-13 18:42:33",
"id": 123412341234,
"job_id": "Pm3oCUf5CSVKIOt4mAqOzdt6K3qInj1431542432",
"member_id": 958,
"created_on": "2015-08-13 18:40:32",
"last_modified": "2015-08-13 18:42:33"
}

Afficher votre historique de chargement de fichiers

Pour afficher les métadonnées relatives à tous vos chargements de fichiers de segments au cours des 30 derniers jours, effectuez un GET appel au service avec votre member_id spécifié dans la chaîne de requête. La réponse JSON inclut un tableau d’objets batch_segment_upload_job . Pour plus d’informations sur les champs spécifiques de l’objet batch_segment_upload_job , consultez Champs JSON ci-dessous.

Remarque

L’historique de chargement de fichiers est disponible pour les 30 derniers jours uniquement.

m$ curl -b cookies 'https://api.appnexus.com/batch-segment?member_id=456'

{
   "response" : {
      "batch_segment_upload_job" : [
         {
           "phase": "completed",
            "start_time": "2012-05-22 16:48:55",
            "uploaded_time": "2012-05-22 16:48:56",
            "validated_time": "2012-05-22 16:49:01",
            "completed_time": "2012-05-22 16:49:01",
            "error_code": null,
            "time_to_process": "0.04",
            "percent_complete": 100,
            "num_valid": 0,
            "num_invalid_format": 0,
            "num_invalid_user": 2,
            "num_invalid_segment": 0,
            "num_unauth_segment": 1,
            "num_past_expiration": 0,
            "num_inactive_segment": 0,
            "num_other_error": 0,
            "error_log_lines": " \n\nnum_unauth_segment-4013681496264948522;5013:0,5014:1550\nnum_invalid_user-7652266028043224430;5848:0,5849:1440,5850:1440\nnum_invalid_user-8802117132500293405;5851:0,5847:-1",
            "id": 98,
            "job_id": "T1v98eIOlCZndeLGSXD0nrs57L8ES11337705335",
            "member_id": 456,
            "created_on": "2012-05-22 16:48:55",
            "last_modified": "2012-05-22 16:49:01"
         },
     ...
    }
  }
}

Remarque

Notre API limite les réponses à 100 objets via la pagination. Vous pouvez afficher des objets supplémentaires en ajoutant l’un d’entre eux à l’appel d’API :

&start_element=101
&sort=last_modified.desc

Pour plus d’informations sur la pagination , consultez Limitation, pagination et filtrage.

API REST

HTTP, méthode	Endpoint	Description
`GET`	`https://api.appnexus.com/batch-segment/meta`	Pour déterminer les champs que vous pouvez filtrer et trier, effectuez un `GET` appel.

Champs JSON

Champ	Type	Description
`batch_segment_upload_job`	objet	Objet dont les champs contiennent des métadonnées décrivant le travail de chargement et de traitement. Si vous utilisez l’API Impbus, il s’agit d’un tableau contenant un seul objet. Pour plus d’informations, consultez la section Batch Segment Upload Job ci-dessous.
`id`	int	Il s’agit de l’ID de l’objet `batch_segment_upload_job` associé à cette demande. Valeur par défaut : nombre généré automatiquement.
`status`	string	Status de l’appel d’API ; les appels réussis retournent `"OK"`.

Tâche de chargement de segment batch

Lorsque vous demandez la status de votre travail de traitement, le système retourne un batch_segment_upload_job objet (si vous êtes un fournisseur de données, il s’agit d’un tableau contenant un seul objet). Selon la demande que vous adressez au service, elle contient tout ou partie des métadonnées suivantes. Pour plus d’informations sur la séquence requise de demandes, consultez la section Ajouter un fichier de segment pour le traitement ci-dessous.

Remarque

La plupart des métadonnées sont uniquement présentes lorsque phase = "completed".

Champs	Type	Description
`completed_time`	date	Heure à laquelle le traitement du fichier a été effectué.
`created_on`	date	Date de création de cet objet.
`error_code`	int	Si la valeur est `phase='error'`, ce code d’erreur décrit le type d’erreur rencontré. Notez qu’un code d’erreur ne s’affiche ici que s’il y a eu une erreur lors du chargement, de la validation ou du traitement du fichier lui-même (c’est-à-dire qu’il n’inclut pas d’erreurs de format ou de segment non valides). Les erreurs courantes sont dues à des fichiers illisibles et au dépassement des limites d’objets définies. Retourne `null` si aucune erreur n’a été trouvée.
`error_log_lines`	chaîne	Chaîne contenant des lignes séparées par de nouvelles lignes. Chaque ligne répertorie une erreur de validation ou la raison d’une erreur lors du chargement de votre fichier. Vous pouvez choisir le nombre de lignes (par défaut, 200) qui s’affichent dans ce champ.
`id`	int	Identificateur unique de cet objet.
`job_id`	string	Chaîne de caractères alphanumériques qui identifie de façon unique le travail de traitement associé à ce fichier.
`last_modified`	date	Date de modification la plus récente de cet objet (généralement via `POST`).
`member_id`	int	Votre ID de membre.
`num_inactive_segment`	int	Nombre de segments inactifs dans le fichier. Dédupliqué.
`num_invalid_format`	int	Nombre de lignes chargées contenant des erreurs de mise en forme (cela dépend de votre configuration de format de fichier particulière). Les lignes dupliquées sont également considérées comme un format non valide.
`num_invalid_segment`	int	Nombre de segments non valides dans le fichier. Dédupliqué.
`num_invalid_timestamp`	int	Nombre d’horodatages non valides dans le fichier.
`num_invalid_user`	int	Il s’agit d’un nombre de lignes d’entrée uniques qui ont un utilisateur non valide ou inexistant.
`num_other_error`	int	Il s’agit d’une valeur d’espace réservé qui n’est pas en cours d’utilisation.
`num_past_expiration`	int	Nombre de segments expirés dans le fichier. Dédupliqué.
`num_unauth_segment`	int	Nombre de segments du fichier auxquels vous n’êtes pas autorisé à accéder. Dédupliqué.
`num_valid`	int	Nombre de lignes valides dans le fichier chargé. Chaque combinaison utilisateur/segment est considérée comme une seule ligne.
`num_valid_user`	int	Il s’agit d’un nombre de lignes d’entrée uniques qui ont un ID utilisateur valide.
`percent_complete`	int	Pourcentage du traitement qui a été effectué, compte tenu de la valeur actuelle `phase` au moment de la demande.
`phase`	enum	Status de traitement actuel. Retourne l’une des valeurs suivantes : - `"error"` - `"starting"` - `"uploading"` - `"validating"` - `"processing"` - `"completed"`
`segment_log_lines`	string	Chaîne contenant des lignes séparées par de nouvelles lignes. Chaque ligne répertorie un segment et le nombre d’utilisateurs qui y ont été correctement ajoutés. Ce champ est défini par défaut sur 200 lignes.
`start_time`	date	Heure à laquelle le chargement du fichier a commencé.
`time_to_process`	decimal	Durée du traitement des fichiers de segments, mesurée en minutes.
`upload_url`	chaîne	URL dans laquelle vous allez charger votre fichier de données de segment.
`uploaded_time`	date	Heure à laquelle le fichier associé à cet ID de travail a été chargé.
`validated_time`	date	Heure à laquelle la validation du fichier a été effectuée.

Remarque

Le ciblage peut, dans certains cas, englober les ID associés liés au même utilisateur. Dans ce cas, les identificateurs dans les journaux d’exposition représentent le même utilisateur que l’ID chargé.

Service de segment batch - Format de fichier

Last updated on 2025-10-22

Partager via

API de plateforme numérique - Service de segment batch

Ajouter un fichier de segment pour le traitement

Étape 1. Demander une URL de chargement et un ID de travail

Étape 2. Publier le fichier dans l’URL de chargement

Exemple d’URL de chargement SSL

Étape 3. Vérifier la status du travail

Erreurs de chargement possibles

Tentative de chargement d’un fichier supérieur à 0,5 Go

Code d’erreur dans le travail de chargement de segment de lot

Tentative de dépassement de la limite quotidienne de chargement d’octets

Tentative de dépassement de la limite de chargement d’octets horaire

Tentative de dépassement de la limite de chargement de lignes quotidiennes

Tentative de dépassement de la limite de chargement de lignes horaires

Dépassement de la durée maximale de chargement

Erreurs de traitement possibles

Format non valide

num_invalid_format et error_log_lines exemple

Afficher votre historique de chargement de fichiers

API REST

Champs JSON

Tâche de chargement de segment batch

Rubrique connexe

Ressources supplémentaires

`num_invalid_format` et `error_log_lines` exemple