Implantar e gerenciar solicitações com o serviço de agregação

Depois de implantar o serviço de agregação, use os endpoints createJob e getJob para interagir com ele. O diagrama a seguir mostra uma representação visual da arquitetura de implantação desses dois endpoints:

Visão geral da API Aggregation Service
Figura 1.Visão geral da API Aggregation Service

Leia mais sobre os endpoints createJob e getJob na documentação da API Aggregation Service.

Criar um job

Para criar um job, envie uma solicitação POST para o endpoint createJob. bash POST https://<api-gateway>/stage/v1alpha/createJob -+ Exemplo do corpo da solicitação para createJob:

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<input_bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<output_bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<output_domain_bucket_name>",
    "attribution_report_to": "<reporting origin of report>",
    "reporting_site": "<host name of reporting origin>"
  }
}

A criação de um job bem-sucedida resulta em um código de status HTTP 202.

reporting_site e attribution_report_to são exclusivas uma da outra, e apenas uma delas é necessária.

Também é possível solicitar um job de depuração adicionando debug_run ao job_parameters. Para mais informações sobre o modo de depuração, consulte nossa documentação da execução de depuração de agregação.

{
  "job_request_id": "<job_request_id>",
  "input_data_blob_prefix": "<report_folder>/<report_name>.avro",
  "input_data_bucket_name": "<input_bucket_name>",
  "output_data_blob_prefix": "<output_folder>/<summary_report_prefix>",
  "output_data_bucket_name": "<output_bucket_name>",
  "job_parameters": {
    "output_domain_blob_prefix": "<output_domain_folder>/<output_domain>.avro",
    "output_domain_bucket_name": "<output_domain_bucket_name>",
    "attribution_report_to": "<reporting origin of report>"
    "debug_run": "true"
  }
}

Campos de solicitação

Parâmetro Tipo Descrição
job_request_id String É um identificador exclusivo gerado pela adtech que precisa ser composto por letras ASCII com 128 caracteres ou menos. Isso identifica a solicitação de job em lote e recebe todos os relatórios AVRO agregáveis especificados em "input_data_blob_prefix" do bucket de entrada especificado em "input_data_bucket_name" que está hospedado no armazenamento em nuvem da adtech.
Caracteres: `a-z, A-Z, 0-9, !"#$%&'()*+,-./:;<=>?@[\]^_`{}~
input_data_blob_prefix String Esse é o caminho do bucket. Para arquivos únicos, use o caminho. Para vários arquivos, use o prefixo no caminho.
Exemplo: a pasta/arquivo coleta todos os relatórios de folder/file1.avro, folder/file/file1.avro e folder/file1/test/file2.avro.
input_data_bucket_name String É o bucket de armazenamento para os dados de entrada ou relatórios agregáveis. Isso está no armazenamento em nuvem da adtech.
output_data_blob_prefix String Esse é o caminho de saída no bucket. Um único arquivo de saída é aceito.
output_data_bucket_name String Este é o bucket de armazenamento para onde o output_data é enviado. Ele está no armazenamento em nuvem da adtech.
job_parameters Dicionário Campo obrigatório. Esse campo contém campos diferentes, como:
  • output_domain_blob_prefix
  • output_domain_bucket_name
  • attribution_report_to
  • reporting_site
  • debug_privacy_epsilon
  • report_error_threshold_percentage
job_parameters.output_domain_blob_prefix String Semelhante a input_data_blob_prefix, este é o caminho no output_domain_bucket_name em que o AVRO do domínio de saída está localizado. Para vários arquivos, use o prefixo no caminho. Depois que o serviço de agregação concluir o lote, o relatório de resumo será criado e colocado no bucket de saída output_data_bucket_name com o nome output_data_blob_prefix.
job_parameters.output_domain_bucket_name String É o bucket de armazenamento do arquivo AVRO do domínio de saída. Isso está no armazenamento em nuvem da adtech.
job_parameters.attribution_report_to String Esse valor é mutuamente exclusivo de "reporting_site". É o URL ou a origem do relatório em que o relatório foi recebido. A origem do site é registrada na integração do serviço de agregação.
job_parameters.reporting_site String Mutuamente exclusivo com attribution_report_to. É o nome do host do URL ou da origem do relatório em que o relatório foi recebido. A origem do site é registrada na integração do serviço de agregação. Observação: é possível enviar vários relatórios com origens diferentes em uma única solicitação, desde que todas as origens pertençam ao mesmo site de relatórios especificado neste parâmetro.
job_parameters.debug_privacy_epsilon Ponto flutuante, duplo Campo opcional. Se nenhum valor for transmitido, o valor padrão será 10. É possível usar um valor de 0 a 64.
job_parameters.report_error_threshold_percentage Duplo Campo opcional. Essa é a porcentagem máxima de relatórios com falhas permitida antes que o job falhe. Se for deixado em branco, o valor padrão será 10%.
job_parameters.input_report_count valor longo Campo opcional. O número total de relatórios fornecidos como dados de entrada para o job. Esse valor, em conjunto com report_error_threshold_percentage, permite a falha precoce do job quando os relatórios são excluídos devido a erros.
job_parameters.filtering_ids String Campo opcional. Uma lista de IDs de filtragem não assinados separados por vírgulas. Todas as contribuições que não correspondem ao ID de filtro são filtradas. (por exemplo, "filtering_ids": "12345,34455,12"). O valor padrão é 0.
job_parameters.debug_run Booleano Campo opcional. Ao executar uma execução de depuração, os relatórios de resumo de depuração com e sem ruído e as anotações são adicionados para indicar quais chaves estão presentes na entrada e/ou nos relatórios do domínio. Além disso, as duplicações entre lotes também não são aplicadas. A execução de depuração considera apenas relatórios com a flag "debug_mode": "enabled". A partir da v2.10.0, as execuções de depuração não consomem o orçamento de privacidade.

Receber um job

Quando uma adtech quer saber o status de um lote solicitado, ela pode chamar o endpoint getJob. O endpoint getJob é chamado usando uma solicitação HTTPS GET com o parâmetro job_request_id.

  GET https://<api-gateway>/stage/v1alpha/getJob?job_request_id=<job_request_id>

Você vai receber uma resposta que retorna o status do job com as mensagens de erro:

{
    "job_status": "FINISHED",
    "request_received_at": "2023-07-17T19:15:13.926530Z",
    "request_updated_at": "2023-07-17T19:15:28.614942839Z",
    "job_request_id": "PSD_0003",
    "input_data_blob_prefix": "reports/output_reports_2023-07-17T19:11:27.315Z.avro",
    "input_data_bucket_name": "ags-report-bucket",
    "output_data_blob_prefix": "summary/summary.avro",
    "output_data_bucket_name": "ags-report-bucket",
    "postback_URL": "",
    "result_info": {
        "return_code": "SUCCESS",
        "return_message": "Aggregation job successfully processed",
        "error_summary": {
            "error_counts": [],
            "error_messages": []
        },
        "finished_at": "2023-07-17T19:15:28.607802354Z"
    },
    "job_parameters": {
        "debug_run": "true",
        "output_domain_bucket_name": "ags-report-bucket",
        "output_domain_blob_prefix": "output_domain/output_domain.avro",
        "attribution_report_to": "https://privacy-sandcastle-dev-dsp.web.app"
    },
    "request_processing_started_at": "2023-07-17T19:15:21.583759622Z"
}

Campos de resposta

Parâmetro Tipo Descrição
job_request_id String Esse é o ID exclusivo do job/lote especificado na solicitação createJob.
job_status String Este é o status da solicitação de trabalho.
request_received_at String A hora em que a solicitação foi recebida.
request_updated_at String A hora em que o job foi atualizado pela última vez.
input_data_blob_prefix String Esse é o prefixo de dados de entrada definido em createJob.
input_data_bucket_name String Esse é o bucket de dados de entrada da adtech em que os relatórios agregáveis são armazenados. Esse campo está definido como createJob.
output_data_blob_prefix String Esse é o prefixo de dados de saída definido em createJob.
output_data_bucket_name String Esse é o bucket de dados de saída da adtech, em que os relatórios de resumo gerados são armazenados. Esse campo está definido como createJob.
request_processing_started_at String A hora em que a tentativa de processamento mais recente foi iniciada. Isso exclui o tempo de espera na fila de jobs. (Tempo total de processamento = request_updated_at - request_processing_started_at)
result_info Dicionário Esse é o resultado da solicitação createJob e consiste em todas as informações disponíveis. Isso mostra os valores return_code, return_message, finished_at e error_summary.
result_info.return_code String O código de retorno do resultado do job. Essas informações são necessárias para solucionar problemas no serviço de agregação.
result_info.return_message String A mensagem de sucesso ou falha retornada como resultado do job. Essas informações também são necessárias para resolver problemas do serviço de agregação.
result_info.error_summary Dicionário Os erros retornados do job. Ele contém o número de relatórios e o tipo de erros encontrados.
result_info.finished_at Carimbo de data/hora O carimbo de data/hora que indica a conclusão do job.
result_info.error_summary.error_counts Lista Isso retorna uma lista das mensagens de erro e do número de relatórios que falharam com a mesma mensagem de erro. Cada contagem de erros contém uma categoria, error_count e description.
result_info.error_summary.error_messages Lista Isso retorna uma lista das mensagens de erro dos relatórios que não foram processados.
job_parameters Dicionário Contém os parâmetros de job fornecidos na solicitação createJob. Propriedades relevantes, como "output_domain_blob_prefix" e "output_domain_bucket_name".
job_parameters.attribution_report_to String Mutuamente exclusivo com reporting_site. Esse é o URL do relatório ou a origem de onde ele foi recebido. A origem faz parte do site registrado na integração do serviço de agregação. Isso é especificado na solicitação createJob.
job_parameters.reporting_site String Mutuamente exclusivo com attribution_report_to. É o nome do host do URL do relatório ou a origem em que o relatório foi recebido. A origem faz parte do site registrado na integração do serviço de agregação. Você pode enviar relatórios com várias origens em uma mesma solicitação, desde que todas pertençam ao mesmo site mencionado neste parâmetro. Isso é especificado na solicitação createJob. Além disso, verifique se o bucket contém apenas os relatórios que você quer agregar no momento da criação do job. Todos os relatórios adicionados ao bucket de dados de entrada com origens correspondentes ao site de relatórios especificado no parâmetro do job são processados. O serviço de agregação considera apenas os relatórios no bucket de dados que correspondem à origem de relatórios registrada do job. Por exemplo, se a origem registrada for https://exampleabc.com, apenas os relatórios de https://exampleabc.com serão incluídos, mesmo que o bucket contenha relatórios de subdomínios (https://1.exampleabc.com etc.) ou domínios totalmente diferentes (https://3.examplexyz.com).
job_parameters.debug_privacy_epsilon Ponto flutuante, duplo Campo opcional. Se nenhum valor for transmitido, o valor padrão 10 será usado. Os valores podem variar de 0 a 64. Esse valor é especificado na solicitação createJob.
job_parameters.report_error_threshold_percentage Duplo Campo opcional. É a porcentagem limite de relatórios que podem falhar antes da falha do job. Se nenhum valor for atribuído, o valor padrão de 10% será usado. Isso é especificado na solicitação createJob.
job_parameters.input_report_count Valor longo Campo opcional. O número total de relatórios fornecidos como dados de entrada para este job. A "report_error_threshold_percentage", combinada com esse valor, aciona a falha precoce do job se um número significativo de relatórios for excluído devido a erros. Essa configuração é especificada na solicitação "createJob".
job_parameters.filtering_ids String Campo opcional. Uma lista de IDs de filtragem não assinadas separadas por vírgulas. Todas as contribuições que não correspondem ao ID de filtragem são filtradas. Isso é especificado na solicitação createJob. (por exemplo, "filtering_ids":"12345,34455,12". O valor padrão é "0".)