Compartilhar via

Objetos de banco de dados expandidos 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 de banco de dados ou contêineres. Esses objetos de banco de dados distintos exigem uma configuração personalizada para mapear diretamente para pontos de extremidade REST ou GraphQL. Algumas configurações personalizadas são necessárias para usar o construtor de API de Dados com exibições e procedimentos armazenados.

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

Modos de exibição

As exibições podem ser usadas de forma semelhante à forma como uma tabela pode ser usada no construtor de API de Dados. O uso da 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.

Se você tiver uma exibição, por exemplo, dbo.vw_books_details ela poderá 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"

Nota

--source.key-fields é obrigatório para exibições ao gerar configuração por meio da CLI.

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

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

Nota

Observe que você deve configurar a permissão adequadamente com a capacidade do modo de exibição de ser atualizável ou não. Se uma exibição não estiver atualizável, você só deverá permitir um acesso de leitura à entidade com base nessa exibição.

Suporte rest para exibições

Uma exibição, de uma perspectiva REST, comporta-se como uma tabela. Todas as operações REST têm suporte.

Suporte do GraphQL para exibições

Uma exibição, da perspectiva do GraphQL, se comporta como uma tabela. Todas as operações do GraphQL têm suporte.

Procedimentos armazenados

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

Nota

O construtor de API de Dados dá suporte a 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 poderá 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 seguinte exemplo:

"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 de 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 de API de Dados.
  • Há suporte apenas para os procedimentos armazenados cujos metadados para o primeiro conjunto de resultados descrito por sys.dm_exec_describe_first_result_set.
  • 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.
  • 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.
    • Entidades com suporte de procedimento armazenado não dão suporte a paginação, ordenação ou filtragem. Essas entidades também não dão 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 a entidade com suporte de procedimento armazenado, pode ser configurado para dar suporte a 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 dessa entidade, configure "rest": false e as 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 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 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 do 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 maneira que se alinhe ao comportamento do procedimento armazenado.

Nota

O do GraphQL requer um elemento de consulta para estar presente no esquema. Se você estiver expondo apenas os procedimentos armazenados, certifique-se de ter pelo menos um deles dando suporte à operação de query, caso contrário, você receberá um erro do 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 de 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 runtime:

"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 prefixo. Para o procedimento armazenado anterior, o campo de nome de consulta exato gerado seria executeGetCowrittenBooksByAuthor. O tipo GraphQL 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 runtime:

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

O esquema GraphQL gerado é:

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

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

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

Conteúdo relacionado