Administradores do Enterprise federal podem consultar programaticamente o consumo de ACU e gerenciar grupos, disponibilidade de modelos e limites de ACU usando uma API com chave de serviço. Um SDK Python encapsula todos os endpoints descritos nesta seção.
Os endpoints de gerenciamento de grupos e de limite de ACU estão disponíveis somente em implantações federais auto-hospedadas e multi-tenant. Eles não são disponibilizados em implantações comerciais. Os endpoints de análises (/Analytics, /UserPageAnalytics e /CascadeAnalytics) também verificam o nível de acesso a análises da implantação; uma equipe sem acesso a análises recebe permission_denied.
Todas as requisições são do tipo JSON POST e direcionadas ao servidor de API da sua implantação:
Substitua <your-server> pelo domínio da API da sua implantação federal.
Todas as requisições são autenticadas com uma chave de serviço incluída no corpo da requisição:
Para criar uma chave de serviço, faça login no portal federal como administrador da equipe e acesse Configurações → Chaves de serviço. Em seguida, crie uma chave com as permissões exigidas pelos endpoints que você pretende chamar.
Mantenha as chaves de serviço seguras. Nunca as exponha em código do lado do cliente nem faça commit delas em repositórios.
- As chaves com escopo de equipe podem consultar dados de toda a equipe e gerenciar todos os grupos da equipe.
- As chaves com escopo de grupo são limitadas ao grupo atribuído. Elas podem ler o total agregado de ACUs do grupo e as linhas de usuários, listar e ler somente esse grupo e ler ou atualizar limites de ACU apenas para os membros atuais desse grupo. Elas não podem ler os totais de toda a equipe nem as linhas de usuários, visualizar outros grupos ou criar grupos.
As listas de grupos, de membros de grupos e de linhas de ACU por usuário são paginadas:
page_size — opcional; o padrão é 100 e o máximo é 1.000. Omiti-lo ou informar 0 usa o valor padrão.next_page_token — retornado quando houver mais resultados. Envie-o novamente como page_token em uma requisição idêntica em todos os demais aspectos (incluindo o mesmo page_size) para buscar a próxima página.
Os tokens de página são opacos e criptografados. Eles expiram após 24 horas. Os tokens de consumo de ACU são vinculados ao endpoint, à equipe, ao escopo, ao período, à seleção de grupos e ao tamanho da página. Os tokens das listas de grupos e de membros são vinculados ao endpoint, à equipe, ao escopo e ao tamanho da página. Alterar um valor vinculado entre páginas retorna um erro invalid_argument.
Os erros são retornados em JSON com um código e uma mensagem:
