O que são as APIs REST para Serviços de Relatórios?

Aplica-se a: SQL Server Reporting Services (versões de 2017 e posteriores) Power BI Report Server

O Microsoft SQL Server 2017 Reporting Services suporta APIs de Transferência de Estado Representacional (REST). As APIs REST são endpoints de serviço que suportam um conjunto de operações HTTP (métodos). Estes métodos fornecem acesso para criar, recuperar, atualizar ou eliminar recursos dentro de um servidor de relatórios.

Uma API REST fornece acesso programático aos objetos num catálogo de servidores de relatórios SQL Server 2017 Reporting Services. Seguem-se exemplos de objetos:

• Pastas de Arquivos
• Relatórios
• KPIs
• Fontes de dados
• Conjuntos de dados
• Planos de renovação
• Subscrições

Quando usa uma API REST, pode navegar pela hierarquia de pastas, descobrir o conteúdo de uma pasta ou descarregar uma definição de relatório. Também pode criar, atualizar e eliminar objetos.

Componentes de um pedido/resposta a uma API REST

Um par de pedido/resposta da API REST pode ser separado em cinco componentes:

• O URI do pedido:

  • Embora o URI de pedido esteja incluído no cabeçalho da mensagem de pedido, a maioria das linguagens ou frameworks exige que seja passado separadamente da mensagem de pedido.
  • Consiste em {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}.

  Solicitar URI	Description
  Esquema de URI	Indica o protocolo usado para transmitir o pedido. Por exemplo, http ou https.
  Anfitrião URI	Especifica o nome de domínio ou endereço IP do servidor onde o endpoint do serviço REST está alojado, como myserver.contoso.com.
  Caminho do recurso	Especifica o recurso ou coleção de recursos, que pode incluir múltiplos segmentos usados pelo serviço na determinação da seleção desses recursos. Por exemplo, pode usar CatalogItems(01234567-89ab-cdef-0123-456789abcdef)/Properties para obter as propriedades especificadas para o CatalogItem.
  Cadeia de consulta (opcional)	Fornece parâmetros mais simples, como a versão da API ou critérios de seleção de recursos.

• Campos do cabeçalho da mensagem de pedido HTTP:

  • Um método HTTP obrigatório, também conhecido como operação ou verbo.
  • Diz ao serviço que tipo de operação está a pedir. As APIs REST dos Serviços de Relatórios suportam métodos DELETE, GET, HEAD, PUT, POST e PATCH.
  • Campos de cabeçalho adicionais opcionais, conforme exigido pelo URI e método HTTP especificados.

• Campos opcionais do corpo da mensagem de pedido HTTP:

  • Suporta a operação URI e HTTP. Por exemplo, as operações POST contêm objetos codificados em Multipurpose Internet Mail Extensions (MIME) que são passados como parâmetros complexos.
  • Para operações POST ou PUT, o tipo de codificação MIME para o corpo deve também ser especificado no cabeçalho do Content-type pedido. Alguns serviços exigem que utilize um tipo específico de MIME, como application/json.

• Campos de cabeçalho da mensagem de resposta HTTP:

  • Um código de estado HTTP, que vai desde códigos de sucesso 2xx até códigos de erro 4xx ou 5xx. Em alternativa, pode ser devolvido um código de estado definido pelo serviço, conforme indicado na documentação da API.
  • Campos de cabeçalho adicionais opcionais, conforme necessário para suportar a resposta do pedido, como um Content-type cabeçalho de resposta.

• Campos opcionais do corpo da mensagem de resposta HTTP:

  • Os objetos de resposta codificados em MIME são devolvidos no corpo da resposta HTTP, como uma resposta de um método GET que está a devolver dados. Normalmente, estes objetos são devolvidos num formato estruturado como JSON ou XML, conforme indicado pelo Content-type cabeçalho de resposta.

Documentação da API

Uma API REST moderna exige documentação moderna da API. Uma API REST é construída sobre a especificação OpenAPI, também chamada de especificação swagger. A documentação da API REST do Power BI Report Server está disponível no Microsoft Learn.

Chamadas API de teste

Se precisar de uma ferramenta para testar mensagens de pedido/resposta HTTP, o Fiddler é um proxy gratuito de depuração web que pode interceptar os seus pedidos REST, facilitando o diagnóstico das mensagens de pedido/resposta HTTP.

Conteúdo relacionado

• Utilize as APIs REST do servidor de relatórios do Power BI
• Reporting-Services amostras
• Tente perguntar ao fórum do Reporting Services