Construir e configurar uma ferramenta

Comece com a documentação oficial da API do serviço comercial e uma tarefa que sua conta tem permissão para executar. Uma ferramenta restrita e bem descrita é mais fácil de testar do que uma ferramenta genérica que aceita URL e método arbitrários.

Defina a solicitação#

Dê à ferramenta um nome estável e uma descrição que explique sua finalidade, limites importantes e se ela altera dados. Selecione o método HTTP e o endpoint documentados. Use espaços reservados apenas para os elementos do caminho variável que a operação realmente permite.

Para uma pesquisa de registro fictícia, o caminho pode conter um identificador de registro. O nome do host e a região da conta devem permanecer parte da conexão configurada, em vez da entrada do modelo aberto.

Definir e mapear entradas#

Use o esquema de entrada para descrever cada campo, seu tipo, status obrigatório e valores válidos. Um pequeno esquema para uma pesquisa fictícia é:

{
  "type": "object",
  "properties": {
    "record_id": {
      "type": "string",
      "description": "The verified identifier of the record to read"
    }
  },
  "required": ["record_id"],
  "additionalProperties": false
}

Mapeie argumentos para o caminho documentado, consulta ou campos de corpo. Verifique se os campos obrigatórios ausentes e os argumentos extras inesperados falham claramente. Mantenha a autenticação na conexão do servidor compatível, não em um prompt, esquema de exemplo ou cabeçalho de ferramenta codificado.

Moldar a saída#

O mapeamento ou transformação de resposta pode retornar os campos necessários ao fluxo de trabalho, em vez de uma resposta de serviço inteira. Verifique a saída transformada em relação ao resultado do teste original. Não remova o identificador do registro, as informações de paginação ou os detalhes do erro necessários para entender se o resultado está completo.

Revise as configurações operacionais#

A configuração da ferramenta oferece suporte a configurações de tempo limite, cache e nova tentativa. Use o cache somente quando dados obsoletos forem aceitáveis; uma leitura em cache não é adequada como prova final de que uma gravação acabou de ser concluída. Tentar novamente uma gravação não idempotente pode criar duplicatas, portanto, escolha o comportamento de nova tentativa nas garantias documentadas da API.

Teste o caminho real#

Verifique a entrada correta, a entrada inválida, os resultados vazios, a falha de permissão e uma chamada bem-sucedida limitada. Os diagnósticos de teste podem conter informações confidenciais de solicitação; inspecione-os apenas por meio da rota aprovada do administrador e edite antes de compartilhar. Ver testando antes que um cliente use a ferramenta.