Práticas recomendadas

Esta página aborda várias práticas recomendadas que precisam ser consideradas ao desenvolver aplicativos com a API Google Ad Manager.

Reutilizar clientes/stubs de serviço durante uma execução

A criação de um novo cliente/stub de serviço tem um custo marginal associado à busca da WSDL e à alocação de recursos. Se possível, crie o cliente/stub de serviço uma vez no início de uma execução e disponibilize-o para classes e funções conforme necessário.

Usar paginação ao buscar objetos

Todos os serviços aceitam um método get*ByStatement(), que permite a filtragem de resultados usando a sintaxe PQL. As cláusulas LIMIT e OFFSET podem ser usadas para dividir grandes conjuntos de resultados em páginas, evitando tempos limite e mantendo os tamanhos de página de resposta razoáveis. O tamanho de página sugerido é de 200 a 500, dependendo da complexidade dos objetos.

Solicitações de atualização em lote

Ao alterar vários objetos do mesmo tipo, você pode melhorar o desempenho enviando todos os objetos na mesma solicitação update*(). Há uma sobrecarga marginal no cliente e no servidor para cada solicitação, e os lotes podem ser uma forma eficaz de reduzir o número de solicitações. Por exemplo, use updateOrders para atualizar um lote de Orders em vez de um único pedido em cada chamada.

Usar parâmetros de vinculação na PQL

Os parâmetros de vinculação são uma maneira de colocar variáveis em uma instrução de consulta de PQL. A PQL se refere a uma variável de vinculação por um nome sem espaços e começando com dois-pontos, por exemplo, :name. Há um exemplo de código na página Sintaxe da PQL.

Recomendamos o uso de variáveis de vinculação porque elas melhoram a legibilidade do código, eliminando a necessidade de concatenar strings e variáveis em uma instrução de consulta. Elas também facilitam a reutilização das instruções PQL, já que novas consultas podem ser feitas com a substituição dos valores do parâmetro de vinculação.

Conceder privilégios ao usuário com moderação

Ao usar UserService para criar/atualizar funções de usuário, tenha cuidado para não conceder privilégios a usuários que não precisam deles. Muitos recursos da API podem ser acessados com uma combinação de funções, em vez de atribuir ao usuário uma função de administrador. Consulte a documentação de permissões para decidir quais funções atribuir a um usuário. Além disso, como desenvolvedor de aplicativos terceiros, determine qual nível de acesso seu aplicativo precisa ao solicitar que uma rede crie um usuário para você. Um papel com menos privilégios do que o administrador pode ser suficiente.

Ficar abaixo dos limites de cota

A API Ad Manager aplica vários limites de cota para maior robustez. É importante manter os aplicativos dentro desses limites e saber como responder a qualquer um dos erros de cota que a API pode retornar.

Cota de API

A primeira cota aplicada às solicitações de API é no nível da rede. Para contas do Ad Manager 360, o limite é de oito solicitações por segundo e, para contas do Ad Manager, é de duas solicitações por segundo. Ultrapassar esse limite resulta em um erro QuotaError.EXCEEDED_QUOTA. Todas as solicitações de API feitas na sua rede se aplicam a essa cota, incluindo aplicativos de terceiros que você ou alguém da sua empresa concedeu à API acesso à sua rede.

Cotas específicas do sistema

A cota de API por si só não é suficiente para proteger adequadamente certos sistemas que consomem muitos recursos no Ad Manager. Os sistemas de relatórios e previsão definem as próprias cotas que podem resultar em erros de API: QuotaError.REPORT_JOB_LIMIT e ForecastError.EXCEEDED_QUOTA, respectivamente.

Como lidar com erros de cota

Se o aplicativo encontrar algum dos erros de cota acima, realize uma estratégia para repetir a solicitação de API. Recomendamos aguardar pelo menos cinco segundos primeiro e, se o erro continuar, use a espera exponencial para aumentar o tempo entre novas tentativas. Se a nova tentativa não funcionar, faça uma auditoria dos aplicativos de API para ver se algum usuário na rede está drenando sua cota.