Compartilhar via

Solucionar problemas de uso do construtor de API de dados para bancos de dados do Azure

  • Artigo

Este artigo fornece soluções para erros comuns que podem ocorrer quando você usa o construtor de API de Dados para bancos de dados do Azure.

Endpoint genérico: erro HTTP 400 "Bad Request"

As seções a seguir descrevem as causas e soluções para o erro HTTP 400 "Bad Request".

Ponto de extremidade do construtor de API de dados inválido

A base do componente de caminho da URL é mapeada para o endpoint REST ou GraphQL do construtor da API de dados. Quando a base do componente de caminho da URL não corresponde ao valor definido na configuração de tempo de execução do Criador de API de Dados, o Construtor de API de Dados retorna um erro HTTP 400 "Solicitação incorreta".

Você pode configurar os caminhos raiz para os endpoints GraphQL e REST na runtime seção da configuração de tempo de execução do Criador de API de dados. Você deve usar os valores para iniciar os caminhos de URL para os pontos de extremidade REST e GraphQL.

Por exemplo, as seguintes configurações são definidas /api como o caminho raiz do endpoint REST e /graphql como a raiz do endpoint GraphQL:

"runtime": {
    "rest": {
      "enabled": true,
      "path": "/api"
    },
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "...": "...",
}

Portanto, os valores que você deve usar no início dos caminhos de URL para os endpoints REST e GraphQL são:

/api/<entity>

/graphql

Observação

Ao usar o construtor de API de dados com os Aplicativos Web Estáticos usando o recurso Conexões de Banco de Dados, o caminho da URL começa com /data-api. Você pode adicionar o valor do ponto de extremidade desejado após esse valor. Por exemplo, /data-api/api/<entity> para REST e /data-api/graphql para GraphQL.

Problema de configuração de conexões de banco de dados de aplicativos Web estáticos

Ao usar o construtor de API de Dados com o recurso Conexões de Banco de Dados de Aplicativos Web Estáticos, você encontra o erro "O código de status de resposta não indica êxito: 400 (Solicitação Incorreta)" no corpo da resposta:

{"Message":"{\u0022Message\u0022:\u0022Response status code does not indicate success: 400 (Bad Request).\u0022,\u0022ActivityId\u0022:\u0022<GUID>\u0022}","ActivityId":"<GUID>"}

Esse erro pode indicar um problema com a configuração fornecida ao vincular seu banco de dados.

Para resolver esse problema, siga estas etapas:

  1. Valide se as credenciais do banco de dados são válidas em uma ferramenta como o Azure Data Studio ou o SQL Server Management Studio (SSMS).
  2. Desvincule/revincule o banco de dados conectado.

Se você ainda encontrar o erro, selecione Permitir que serviços e recursos do Azure acessem este servidor para as Exceções na página de rede do recurso do Banco de Dados do Azure. Essa opção configura o firewall para permitir conexões de endereços IP alocados a qualquer serviço ou ativo do Azure, incluindo conexões de assinaturas de outros clientes.

Captura de tela que mostra a caixa de seleção 'Permitir que serviços e recursos do Azure acessem este servidor'.

Ponto de extremidade REST: erro HTTP 404 "Não encontrado"

Se a URL solicitada apontar para uma rota que não está associada a nenhuma entidade, um erro HTTP 404 será retornado. Por padrão, o nome da entidade também é o nome da rota. Por exemplo, se você configurar a entidade de exemplo Todo no arquivo de configuração, como no exemplo a seguir:

"Todo": {
      "source": "dbo.todos",
      "...": "..."
    }

Em seguida, a Todo entidade pode ser acessada por meio da seguinte rota:

/<rest-route>/Todo

Se você especificar a rest.path propriedade na configuração da entidade como todo, conforme mostrado no exemplo a seguir:

"Todo": {
    "source": "dbo.todos",
    "rest": {
      "path": "todo"
    },
    "...": "..."
  }

Em seguida, a rota de URL para a Todo entidade é todo, com todos os caracteres minúsculos correspondendo ao valor exato definido na configuração de tempo de execução:

/<rest-route>/todo

Ponto de extremidade do GraphQL: erro HTTP 400 "Bad Request"

Uma solicitação do GraphQL resulta em um erro HTTP 400 "Bad Request" toda vez que a solicitação do GraphQL é construída incorretamente. Pode ser devido a um campo de entidade inexistente ou a um nome de entidade com erro ortográfico. O construtor de API de dados retorna um erro descritivo e detalhes de erro na carga de resposta.

Quando você envia uma GET solicitação para o ponto de extremidade do GraphQL, o corpo da resposta do erro retornado afirma: "A consulta de parâmetro ou a ID do parâmetro deve ser definida". Certifique-se de enviar suas solicitações do GraphQL usando HTTP POST.

Ponto de extremidade do GraphQL: erro HTTP 404 "Não encontrado"

Certifique-se de que a solicitação do GraphQL seja enviada para o endpoint do GraphQL configurado usando o método HTTP POST . Por padrão, a rota do ponto de extremidade do GraphQL é /graphql.

Endpoint do GraphQL: erro "O tipo de objeto Query deve definir pelo menos um campo para ser válido"

Quando a inicialização do Data API Builder não consegue gerar um esquema GraphQL com base na configuração do tempo de execução, você recebe a mensagem de erro:

O tipo de objeto Query deve definir pelo menos um campo para ser válido.

A especificação do GraphQL requer que pelo menos um Query objeto seja definido no esquema do GraphQL. Você deve validar se sua configuração de tempo de execução atende a uma das seguintes condições:

  • A read ação é definida para pelo menos uma entidade habilitada para GraphQL. O GraphQL está habilitado em entidades por padrão, portanto, certifique-se de não aplicar essa mitigação a uma entidade configurada com {"graphql": false}.

  • Quando você expõe apenas procedimentos armazenados, defina { "graphql": { "operation": query" } } pelo menos uma entidade de procedimento armazenado, que substitui o tipo mutationde operação GraphQL de procedimento armazenado padrão.

    Você deve ter pelo menos um procedimento armazenado que apenas leia e não modifique os dados. Caso contrário, a geração do esquema do GraphQL falhará devido a um campo vazio query no esquema.

Ponto de extremidade do GraphQL: a introspecção não funciona com o ponto de extremidade do GraphQL

As ferramentas que suportam o GraphQL normalmente utilizam a introspecção do esquema do GraphQL sem exigir configuração extra. Certifique-se de definir a propriedade allow-introspection de configuração de tempo de execução como true na seção de runtime.graphql configuração. Por exemplo:

"runtime": {
    "...": "...",
    "graphql": {
      "allow-introspection": true,
      "enabled": true,
      "path": "/graphql"
    },
    "...": "..."
}

Ponto final do GraphQL: erro "A operação <de mutação operation_name> foi bem-sucedida, mas o usuário atual não está autorizado a visualizar a resposta devido à falta de permissões de leitura"

Para que uma operação de mutação do GraphQL receba uma resposta válida, as permissões de leitura devem ser configuradas além do respectivo tipo de operação de mutação - criar, atualizar e excluir. Como o erro sugere, a operação de mutação (criar/atualizar/excluir) foi bem-sucedida na camada de banco de dados, mas a falta de permissão de leitura fez com que o construtor da API de dados retornasse uma mensagem de erro. Portanto, certifique-se de configurar as permissões de leitura na função "Anônimo" ou na função com a qual você deseja executar a operação de mutação.

Erro geral: erro HTTP 500 retornado por solicitações

Erros HTTP 500 indicam que o construtor da API de dados não pode operar corretamente no banco de dados de back-end. Verifique se as seguintes condições estão atendidas:

  • O construtor de API de dados ainda pode se conectar ao banco de dados configurado.
  • Os objetos de banco de dados usados pelo construtor da API de dados ainda estão disponíveis e acessíveis.

Para permitir que o construtor de API de dados retorne erros de banco de dados específicos em respostas, defina a runtime.host.mode propriedade de configuração como development:

"runtime": {
    [...]
    "host": {
        "mode": "development",
        [...]
    }
}

Por padrão, o construtor de API de dados é executado com runtime.host.mode that's definido como production. No production modo, o construtor de API de dados não retorna erros detalhados no conteúdo da resposta.

Nos modos development e production , o Data API Builder grava erros detalhados no console para ajudar na solução de problemas.

Erros gerais devido a solicitações não autenticadas e não autorizadas

Erro HTTP 401 "Não autorizado"

Os erros HTTP 401 ocorrem quando o ponto de extremidade e a entidade que estão sendo acessados exigem autenticação e o solicitante não fornece metadados de autenticação válidos em sua solicitação.

Quando você configura o construtor de API de dados para usar a autenticação de ID do Microsoft Entra, suas solicitações resultam em erros HTTP 401 quando o token de portador (acesso) fornecido é inválido. Um token de acesso pode ser inválido por vários motivos. Eis algumas delas:

  • O token de acesso expirou.
  • O token de acesso não se destina à API (público-alvo de token de acesso incorreto) do criador da API de dados.
  • O token de acesso não é criado pela autoridade esperada (emissor de token de acesso inválido).

Para resolver esse erro, certifique-se de atender às seguintes condições:

  • Você gera um token de acesso usando o issuer valor definido na authentication seção da configuração de tempo de execução.

  • Seu token de acesso é gerado para o audience valor definido na authentication seção da configuração de tempo de execução.

Veja um exemplo de configuração:

"authentication": {
    "provider": "AzureAD",
    "jwt": {
        "issuer": "https://login.microsoftonline.com/24c24d79-9790-4a32-bbb4-a5a5c3ffedd5/v2.0/",
        "audience": "b455fa3c-15fa-4864-8bcd-88fd83d686f3"
    }
}

Você deve gerar um token válido para o público-alvo definido. Ao usar a CLI do Azure, você pode obter um token de acesso especificando o público-alvo no resource parâmetro:

az account get-access-token --resource "b455fa3c-15fa-4864-8bcd-88fd83d686f3"

Erro HTTP 403 "Proibido"

Se você enviar uma solicitação autenticada usando a integração de Aplicativos Web Estáticos ou a ID do Microsoft Entra, poderá receber um erro HTTP 403 "Proibido". Esse erro indica que você tenta usar uma função que não existe no arquivo de configuração.

Esse erro ocorre quando:

  • Você não fornece um X-MS-API-ROLE cabeçalho HTTP especificando um nome de função.

    Como as solicitações autenticadas são executadas no contexto da função authenticated do sistema por padrão, esse cenário só se aplica quando você usa uma função que não é do sistema (not authenticated nor anonymous).

  • A função definida no X-MS-API-ROLE cabeçalho não está configurada no arquivo de configuração de tempo de execução do Criador de API de Dados.

  • A função definida no X-MS-API-ROLE cabeçalho não corresponde à função no token de acesso.

Por exemplo, no arquivo de configuração de tempo de execução a seguir, a função role1 é definida, portanto, você deve fornecer um X-MS-API-ROLE cabeçalho HTTP com o valor role1.

Observação

A correspondência dos nomes da função diferencia maiúsculas de minúsculas.

"Todo": {
    "role": "role1",
    "actions": [ "*" ]
}

Referências

Próxima etapa

Se o problema não for resolvido, forneça feedback ou informe-o nas Discussões do data-api-builder.

Entre em contato conosco para obter ajuda

Se você tiver dúvidas ou precisar de ajuda, crie uma solicitação de suporte ou peça ajuda à comunidade de suporte do Azure. Você também pode enviar comentários sobre o produto para a comunidade de comentários do Azure.