API de extracción de Manadge

La API de extracción de Manadge le permite extraer y exportar datos de un espacio de trabajo de Manadge de forma segura y eficiente. Esta documentación cubre los extremos disponibles, los formatos de respuesta y los métodos de autenticación.

La API de extracción se basa en la función Exportar del espacio de trabajo de Manadge. Los límites siguen siendo los mismos.

La API de extracción de Manadge es una función opcional disponible por un cargo adicional. Para obtener más información, hable con su administrador de Éxito del Cliente de Triton Digital.

Autenticación y acceso a tokens

La API utiliza autenticación basada en token para garantizar un acceso seguro. Los tokens se generan en el espacio de trabajo de la interfaz de usuario de Manadge y se dedican a cada usuario. Estos tokens son el principal medio de autenticación para acceder a la API.

Uso de tokens

Una vez generado, el token debe ser guardado manualmente por usted (el usuario), ya que no será accesible más adelante. Debe incluir su token como autenticación básica con:

Dirección de correo electrónico utilizada para iniciar sesión en su espacio de trabajo
Token de API generado en su espacio de trabajo

Ciclo de vida del token

Vencimiento: Los tokens caducan cada tres meses, por razones de seguridad.
Actualización: los tokens se pueden actualizar para extender su validez por otros tres meses. Este proceso se gestiona únicamente dentro del espacio de trabajo de la interfaz de usuario de Manadge y no se puede realizar a través de la API.
Revocación: Los tokens se pueden revocar si es necesario. De nuevo, esta acción se administra únicamente dentro del área de trabajo de la interfaz de usuario de Manadge.

Importante: Dado que la administración de tokens (actualización o revocación) se maneja exclusivamente dentro del espacio de trabajo de la interfaz de usuario de Manadge y no a través de la API, debe asegurarse de actualizar o revocar los tokens según sea necesario a través de la página correspondiente.

Puntos de acceso

OBTENER `/config`

La API proporciona un extremo para recuperar las posibilidades de configuración de un informe. Este extremo le permite obtener información sobre dimensiones, métricas, monedas, tarifas y otros criterios disponibles.

Recuperar configuración de extracción de datos
- Extremo: GET /api/stats/extract/config
- Descripción: recupera información sobre dimensiones, métricas, monedas, tarifas y otros criterios disponibles para la extracción de datos.

Ejemplo de solicitud:

curl 'https://<workspace>.manadge.tritondigital.com/api/stats/extract/config' 
-u '<your email adress>:<your access token from api key>' 
-H 'Content-Type: application/json'

Ejemplo de respuesta:

 "views": {
        "auction": {
            "groups": [
                "_all"
            ],
            "id": "auction",
            "name": "Auction",
            "dimensions": [
                {
                    "name": "Creative Language",
                    "null_name": "Creative Language Undefined",
                    "id": "creative_language",
                    "type": "dimension",
                    "source": "dimension",
                    "description": "Language of the creative (provided on the bid response)",
                    "can_filter": true
                },
                {
                    "name": "Device Global Region",
                    "null_name": "Device Global Region Undefined",
                    "id": "device_global_region",
                    "type": "dimension",
                    "source": "dimension",
                    "description": "Global territory of bid, retrieved from the IP address",
                    "can_filter": true
                },
                {
                    "name": "App Store URL",
                    "null_name": "App Store URL Undefined",
                    "id": "app_store_url",
                    "type": "dimension",
                    "source": "dimension",
                    "description": null,
                    "can_filter": true
                },
...
    },
  "bid": {
            "groups": [
                "_all"
            ],
            "id": "bid",
            "name": "Bid",
            "dimensions": [
                {
                    "name": "Bid Response Status",
                    "null_name": "Bid Response Status Undefined",
                    "id": "bid_response_status",
                    "type": "dimension",
                    "source": "dimension",
                    "description": null,
                    "can_filter": true
                },
                {
                    "name": "Creative Language",
                    "null_name": "Creative Language Undefined",
                    "id": "creative_language",
                    "type": "dimension",
                    "source": "dimension",
                    "description": "Language of the creative (provided on the bid response)",
                    "can_filter": true
                },
                {
                    "name": "Device Global Region",
                    "null_name": "Device Global Region Undefined",
                    "id": "device_global_region",
                    "type": "dimension",
                    "source": "dimension",
                    "description": "Global territory of bid, retrieved from the IP address",
                    "can_filter": true
                },"
        },
        ...
        }
    }
}

Debe utilizar el botón /config Ruta para recopilar dimensiones y métricas para su consulta. No use las dimensiones y métricas del ejemplo anterior, ya que podrían cambiar a medida que la API evolucione y algunos elementos podrían ser específicos de cuentas individuales.

PUBLICAR `/extract`

La API proporciona un extremo para generar informes mediante la extracción de archivos ZIP, que incluyen:

Metadatos del informe (Fecha, filtros, dimensiones, período, etc.)
CSV con los datos.

Este extremo le permite especificar parámetros como fechas, moneda, dimensiones, métricas, orden por, filtros y tipo de vista para generar el informe.

Generar informe
- Punto final: POST /api/stats/extract
- Método: POST
- Descripción: genera un informe extrayendo datos en formato Parquet en función de los parámetros especificados.
- Cuerpo de la solicitud:
  - dates: Required. A DateQuery Objeto que representa el intervalo de fechas del informe.
  - dimensions: Required. A list of Dimension objetos que especifican las dimensiones del informe.
    - Debe especificar la id de la dimensión recuperada de la /config consulta.
    - top: Required. Number of top values per dimension is manadory (max value 2000).
  - metrics: Required. A list of strings representing the metrics to be included in the report.
    - Debe especificar la id de la dimensión recuperada de la /config consulta.
  - filters: Required. A dictionary containing key-value pairs for applying filters to the report data. Puede estar vacío si no se aplican filtros.
  - order_by: Required. A string specifying the field to order the report data by.
  - view: Required. A string specifying the view type for the report data (i.e., Auction or bid)
  - fee : Optional. A string representing the fee associated with the report data.
  - currency: Optional. A string representing the currency for the report data.

Ejemplo de solicitud:

curl --location 'https://{workspace}.manadge.tritondigital.com/api/stats/extract' \
-u '<your email adress>:<your access token from api key>'
--header 'Content-Type: application/json' \
--data '{
    "dates": {"from":"2024-04-29T00:00:00Z","to":"2024-04-30T00:00:00Z"},
    "dimensions":[{"name":"advertiser","top":100}],
    "metrics":["sumImpressions"],
    "order_by":"sumImpressions",
    "filters":{},
    "view":"auction"
}'

Ejemplo del cuerpo de una solicitud:

{
  "dates": {"from":"2024-04-29T00:00:00Z","to":"2024-04-30T00:00:00Z"},
  "currency":"USD",
  "dimensions":[{"name":"advertiser","top":10}],
  "metrics":["sumImpressions"],
  "order_by":"sumImpressions",
  "filters":{},
  "view":"bid"
}

Límites y cuotas

Al usar la API de exportación de datos, debe tener en cuenta los siguientes límites y cuotas:

30 reports per company per day: Each company can generate up to 30 reports per day using the Data Export API.
Maximum 6 dimensions per report: Each report can include a maximum of five dimensions.
Unlimited metrics per report: There is no limit to the number of metrics that can be included in a report.

Índice de documentación