> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Exportar registros de chamadas de API da plataforma AceDataCloud

> Platform API guide - Ace Data Cloud

Baixe diretamente os detalhes das chamadas de API da conta atual como CSV, adequado para reconciliação financeira, análise offline ou armazenamento de grandes volumes de registros. Se você precisar apenas visualizar uma pequena quantidade de detalhes na página, use primeiro a [lista de registros de chamadas](https://platform.acedata.cloud/documents/platform-usage-list).

## Preparação

1. Faça login na [plataforma AceDataCloud](https://platform.acedata.cloud).
2. Crie um token de conta no [console Account Token](https://platform.acedata.cloud/console/platform-tokens) e salve-o imediatamente em um gerenciador de senhas ou Secret Manager.
3. Conforme necessário, obtenha IDs de filtro na [lista de solicitações de serviço](https://platform.acedata.cloud/documents/platform-application-list), [lista de credenciais de API](https://platform.acedata.cloud/documents/platform-credential-list) ou [lista de APIs](https://platform.acedata.cloud/documents/platform-api-list).

Para a explicação completa sobre tokens, consulte [gerenciar tokens de conta](https://platform.acedata.cloud/documents/platform-token). O token de conta e a Credential usada para chamar APIs de negócios não podem ser usados de forma intercambiável.

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
```

## Visão geral da interface

| Item | Conteúdo |
| - | - |
| Método | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/export/` |
| Autenticação | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read` (`platform:read` / `platform` incluem de forma expandida) |
| Resposta | `200 text/csv; charset=utf-8` |
| Nome do arquivo | `usages.csv` |

Esta interface retorna o CSV de forma síncrona e em streaming, não cria uma tarefa de exportação e também não retorna JSON nem um link de download. Somente quando os horários de início e fim não são fornecidos é que, por padrão, são exportados os registros do início do mês-calendário atual até o momento atual; quando apenas um limite é fornecido, o outro limite não é automaticamente complementado com o limite deste mês.

## Parâmetros de consulta

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| - | - | - | - | - |
| `perspective` | string | Não | `both` | `billing`, `actor` ou `both` |
| `service_id` | UUID | Não | — | Filtrar por serviço; suporta parâmetros repetidos |
| `application_id` | UUID | Não | — | Filtrar por Application; suporta parâmetros repetidos |
| `api_id` | UUID | Não | — | Filtrar por API; suporta parâmetros repetidos |
| `credential_id` | UUID | Não | — | Filtrar por credencial de API; suporta parâmetros repetidos |
| `status_code` | integer | Não | — | Suporta valores repetidos ou separados por vírgula |
| `created_at_from` | datetime | Não | — | Horário inicial em ISO 8601 |
| `created_at_to` | datetime | Não | — | Horário final em ISO 8601 |

O escopo de exportação é sempre limitado aos registros visíveis para a conta atual como entidade pagadora e/ou chamadora real, e não oferece suporte à exportação entre contas.

## Exemplos de solicitação

Salvar diretamente o CSV do mês atual:

```shell theme={null}
curl --fail-with-body --location \
  'https://platform.acedata.cloud/api/v1/usage/apis/export/' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  --output usages.csv
```

Exportar por Application, horário e código de status:

```shell theme={null}
export APPLICATION_ID='你的 Application ID'

curl --fail-with-body --get \
  'https://platform.acedata.cloud/api/v1/usage/apis/export/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'status_code=200,500' \
  --data-urlencode 'created_at_from=2026-09-01T00:00:00Z' \
  --data-urlencode 'created_at_to=2026-09-08T00:00:00Z' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}" \
  --output usages.csv
```

Salvar em streaming com Python e verificar a integridade:

```python theme={null}
import os
from pathlib import Path

import requests

url = "https://platform.acedata.cloud/api/v1/usage/apis/export/"
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"}
params = {
    "created_at_from": "2026-09-01T00:00:00Z",
    "created_at_to": "2026-09-08T00:00:00Z",
    "perspective": "both",
}
output = Path("usages.csv")

with requests.get(url, headers=headers, params=params, stream=True, timeout=120) as response:
    response.raise_for_status()
    if not response.headers.get("content-type", "").startswith("text/csv"):
        raise RuntimeError("服务器没有返回 CSV")
    with output.open("wb") as file:
        for chunk in response.iter_content(chunk_size=64 * 1024):
            file.write(chunk)

last_line = output.read_text(encoding="utf-8").splitlines()[-1]
if last_line.startswith("# truncated:") or last_line.startswith("# error:"):
    raise RuntimeError(f"导出不完整：{last_line}")
```

## Colunas do CSV

A ordem do cabeçalho do CSV é fixa como:

```text theme={null}
Usage ID,API,Status Code,Deducted Amount,Original Amount,Trace ID,Created At
```

| Coluna | Descrição |
| - | - |
| `Usage ID` | ID do registro de chamada |
| `API` | Título da API; pode ser o ID da API ou vazio quando não for possível corresponder |
| `Status Code` | Código de status HTTP |
| `Deducted Amount` | Valor final efetivamente deduzido |
| `Original Amount` | Valor original antes do desconto da aplicação |
| `Trace ID` | Identificador de rastreamento da solicitação |
| `Created At` | Horário de criação do registro, ISO 8601 |

A unidade de cota é determinada por `service.unit` da Application correspondente.

## Determinar se a exportação está completa

Uma única vez pode produzir no máximo 1.000.000 de registros. Depois que o servidor começa a retornar o CSV, não é possível alterar um erro ocorrido no meio para outro status HTTP, portanto o cliente deve verificar a última linha:

* `# truncated:`: o limite de linhas foi atingido; exporte em segmentos usando janelas de tempo menores.
* `# error:`: a leitura em streaming foi interrompida; reduza o escopo e exporte novamente.

Quando um programa de reconciliação encontrar qualquer marker, ele deve considerar o arquivo incompleto e não pode contabilizá-lo silenciosamente.

## Erros e novas tentativas

| Situação | Forma de tratamento |
| - | - |
| `400 usage_history_expired` | Use `available_from` na resposta para ajustar para o período dos últimos 60 dias |
| `401 not_authenticated` | Verifique se o Account Token existe, está correto e não foi excluído |
| Resposta que não é CSV | Não salve como arquivo de sucesso; primeiro leia a resposta de erro e corrija a solicitação |
| Download interrompido ou marker | Reduza a janela de tempo e exporte novamente usando uma estratégia de recuo |

## Próximos passos

* [Ver registros de chamadas](https://platform.acedata.cloud/documents/platform-usage-list): filtrar online e localizar uma única solicitação.
* [Agregar volume de chamadas](https://platform.acedata.cloud/documents/platform-usage-aggregate): visualizar dados agregados por data, API ou modelo.
* [Ver detalhes da solicitação de serviço](https://platform.acedata.cloud/documents/platform-application-detail): conferir a unidade de cota e a cota restante.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.