Partilhar via

Objetos de banco de dados no construtor de API de dados

  • Artigo

O construtor de API de dados inclui suporte para exibições e procedimentos armazenados como alternativas ao mapeamento para tabelas ou contêineres de banco de dados. Esses objetos de banco de dados distintos exigem configuração personalizada para mapear perfeitamente para pontos de extremidade REST ou GraphQL. Algumas configurações personalizadas são necessárias para usar o Data API builder com exibições e procedimentos armazenados.

Este artigo inclui um detalhamento de como usar exibições e procedimentos armazenados com o Data API builder.

Modos de exibição

As exibições podem ser usadas de forma semelhante a como uma tabela pode ser usada no Data API builder. O uso de exibição deve ser definido especificando o tipo de origem para a entidade como view. Junto com isso, a propriedade key-fields deve ser fornecida, para que o construtor de API de dados saiba como pode identificar e retornar um único item, se necessário.

Observação

As visualizações não suportam relacionamentos.

Se você tiver uma exibição, por exemplo, dbo.vw_books_details ela pode ser exposta usando o seguinte comando dab:

dab add BookDetail --source dbo.vw_books_details --source.type View --source.key-fields "id" --permissions "anonymous:read"

Observação

--source.key-fields é obrigatório para visualizações ao gerar configuração através da CLI.

O arquivo dab-config.json seria como o exemplo a seguir:

"BookDetail": {
  "source": {
    "type": "view",
    "object": "dbo.vw_books_details",
    "key-fields": [ "id" ]
  },
  "permissions": [{
    "role": "anonymous",
    "actions": [ "read" ]
  }]
}

Observação

Observe que você deve configurar a permissão de acordo com a capacidade da exibição de ser atualizável ou não. Se um modo de exibição não for atualizável, você só deverá permitir um acesso de leitura à entidade com base nesse modo de exibição.

Suporte REST para visualizações

Uma vista, de uma perspetiva REST, comporta-se como uma mesa. Todas as operações REST são suportadas.

Suporte GraphQL para visualizações

Uma vista, de uma perspetiva GraphQL, comporta-se como uma tabela. Todas as operações GraphQL são suportadas.

Procedimentos armazenados

Os procedimentos armazenados podem ser usados como objetos relacionados a entidades expostas pelo construtor de API de dados. O uso do Procedimento Armazenado deve ser definido especificando que o tipo de origem da entidade é stored-procedure.

Observação

O construtor de API de dados suporta procedimentos armazenados para bancos de dados relacionais (ou seja, MSSQL), mas não para bancos de dados não relacionais (ou seja, NoSQL).

Se você tiver um procedimento armazenado, por exemplo, dbo.stp_get_all_cowritten_books_by_author ele pode ser exposto usando o seguinte comando dab:

dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" --source.params "searchType:s" --permissions "anonymous:execute" --rest.methods "get" --graphql.operation "query"

O arquivo dab-config.json seria como o exemplo a seguir:

"GetCowrittenBooksByAuthor": {
  "source": {
    "type": "stored-procedure",
    "object": "dbo.stp_get_all_cowritten_books_by_author",
    "parameters": {
      "searchType": "s"
    }
  },
  "rest": {
    "methods": [ "GET" ]
  },
  "graphql": {
    "operation": "query"
  },
  "permissions": [{
   "role": "anonymous",
    "actions": [ "execute" ]
  }]
}

O parameters define quais parâmetros devem ser expostos e também fornece valores padrão a serem passados para os parâmetros do procedimento armazenado, se esses parâmetros não forem fornecidos na solicitação HTTP.

Limitações

  • Somente o primeiro conjunto de resultados retornado pelo procedimento armazenado é usado pelo construtor da API de dados.
  • Somente os procedimentos armazenados cujos metadados para o primeiro conjunto de resultados descrito por sys.dm_exec_describe_first_result_set são suportados.
  • Para pontos de extremidade REST e GraphQL: quando um parâmetro de procedimento armazenado é especificado no arquivo de configuração e na cadeia de caracteres de consulta de URL, o parâmetro na cadeia de caracteres de consulta de URL tem precedência.
  • As entidades apoiadas por um procedimento armazenado não têm todos os recursos fornecidos automaticamente para entidades apoiadas por tabelas, coleções ou exibições.
    • As entidades com suporte de procedimento armazenado não suportam paginação, ordem ou filtragem. Essas entidades também não oferecem suporte ao retorno de itens especificados por valores de chave primária.
    • Não há suporte para regras de autorização de nível de campo/parâmetro.

Suporte REST para procedimentos armazenados

O comportamento do ponto de extremidade REST, para entidade com suporte de procedimento armazenado, pode ser configurado para suportar um ou vários verbos HTTP (GET, POST, PUT, PATCH, DELETE). A seção REST da entidade seria como o seguinte exemplo:

"rest": {
  "methods": [ "GET", "POST" ]
}

Todas as solicitações REST para a entidade falham com Método HTTP 405 Não Permitido quando um método HTTP não listado na configuração é usado. Por exemplo, a execução de uma solicitação PUT falha com o código de erro 405. Se a seção methods for excluída da configuração REST da entidade, o método padrão POST será inferido. Para desabilitar o ponto de extremidade REST para esta entidade, configure "rest": false e quaisquer solicitações REST na entidade de procedimento armazenado falharão com HTTP 404 Não Encontrado.

Se o procedimento armazenado aceitar parâmetros, os parâmetros poderão ser passados na cadeia de caracteres de consulta de URL ao chamar o ponto de extremidade REST com o verbo HTTP GET. Por exemplo:

GET http://<dab-server>/api/GetCowrittenBooksByAuthor?author=isaac%20asimov

Os procedimentos armazenados que são executados usando outros verbos HTTP, como POST, PUT, PATCH, DELETE, exigem que os parâmetros sejam passados como JSON no corpo da solicitação. Por exemplo:

POST http://<dab-server>/api/GetCowrittenBooksByAuthor

{
  "author": "isaac asimov"
}

Suporte GraphQL para procedimentos armazenados

A execução de procedimento armazenado no GraphQL pode ser configurada usando a opção graphql de uma entidade com suporte de procedimento armazenado. Definir explicitamente a operação da entidade permite que você represente um procedimento armazenado no esquema GraphQL de uma forma que se alinhe com o comportamento do procedimento armazenado.

Observação

O GraphQL requer um elemento Query para estar presente no esquema. Se você estiver expondo apenas procedimentos armazenados, certifique-se de ter pelo menos um deles suportando a operação query, caso contrário, você receberá um erro GraphQL como The object type Query has to at least define one field in order to be valid.

Não definir nenhum valor para a operação resulta na criação de uma operação mutation.

Por exemplo, usar o valor query para a opção operation resulta na resolução do procedimento armazenado como um campo de consulta no esquema GraphQL.

Uso da CLI:

dab add GetCowrittenBooksByAuthor --source dbo.stp_get_all_cowritten_books_by_author --source.type "stored-procedure" --source.params "searchType:s" --permissions "anonymous:execute" --rest.methods "GET" --graphql.operation "query"

Configuração de tempo de execução:

"graphql": {
  "operation": "query"
}

Componentes do esquema GraphQL: tipo e campo de consulta:

type GetCowrittenBooksByAuthor {
  id: Int!
  title: String
}

No esquema, as operações de consulta e mutação para procedimentos armazenados têm execute como um prefixo. Para o procedimento armazenado anterior, o campo de nome exato da consulta gerado seria executeGetCowrittenBooksByAuthor. O tipo GraphQL que é gerado é:

type Query {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Como alternativa, operation pode ser definido como mutation para que um campo de mutação represente o procedimento armazenado no esquema GraphQL. O comando dab update pode ser usado para alterar o operation:

dab update GetCowrittenBooksByAuthor --graphql.operation "mutation"

Configuração de tempo de execução:

"graphql": {
  "operation": "mutation"
}

O esquema GraphQL que é gerado é:

type Mutation {
  executeGetCowrittenBooksByAuthor(
    searchType: String = "S"
  ): [GetCowrittenBooksByAuthor!]!
}

Se o procedimento armazenado aceitar parâmetros, esses parâmetros podem ser passados como parâmetro da consulta ou mutação. Por exemplo:

query {
  executeGetCowrittenBooksByAuthor(author:"asimov")
   {
    id
    title
    pages
    year
  }
}

Conteúdo relacionado