O que são as APIs REST para Reporting Services?

  • Artigo

Aplica-se a: SQL Server Reporting Services (2017 e versões posteriores) ❌ Servidor de Relatórios do Power BI

O Microsoft SQL Server 2017 Reporting Services dá suporte a APIs REST (Transferência de Estado Representacional). As APIs REST são pontos de extremidade de serviço que dão suporte a um conjunto de operações HTTP (métodos). Esses métodos fornecem acesso de criação, recuperação, atualização ou exclusão para os recursos em um servidor de relatório.

Uma API REST fornece acesso programático aos objetos em um catálogo do servidor de relatório do SQL Server 2017 Reporting Services. Estes são exemplos de objetos:

  • Pastas
  • Relatórios
  • KPIs
  • Fontes de dados
  • Conjunto de dados
  • Planos de atualização
  • Assinaturas

Ao usar uma API REST, você pode navegar pela hierarquia de pastas, descobrir o conteúdo de uma pasta ou baixar uma definição de relatório. Você também pode criar, atualizar e excluir objetos.

Observação

Se você estiver interessado em exibir ou excluir dados pessoais, examine as diretrizes da Microsoft no site Solicitações de entidades de dados do Windows para o RGPD. Se você estiver procurando informações gerais sobre o RGPD, confira a seção RGPD do Portal de Confiança do Serviço.

Componentes de uma solicitação/resposta da API REST

Um par de solicitação/resposta da API REST pode ser separado em cinco componentes:

  • O URI de solicitação:

    • Embora o URI de solicitação seja incluído no cabeçalho da mensagem de solicitação, a maioria das linguagens ou estruturas exige que ele seja passado separadamente da mensagem de solicitação.
    • Consiste em {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}.
    URI da solicitação Descrição
    Esquema de URI indica o protocolo usado para transmitir a solicitação. Por exemplo, http ou https.
    Host do URI especifica o nome de domínio ou o endereço IP do servidor no qual o ponto de extremidade de serviço REST está hospedado, como myserver.contoso.com.
    Resource path especifica o recurso ou a coleção de recursos, que pode incluir vários segmentos usados pelo serviço para determinar a seleção desses recursos. Por exemplo, você pode usar CatalogItems(01234567-89ab-cdef-0123-456789abcdef)/Properties para obter as propriedades especificadas para o CatalogItem.
    Cadeia de consulta (opcional) Fornece mais parâmetros simples, como a versão de API ou os critérios de seleção de recursos.

  • Campos de cabeçalho de mensagem de solicitação HTTP:

    • Um método HTTP necessário, também conhecido como operação ou verbo.
    • Informa ao serviço que tipo de operação você está solicitando. As APIs REST do Reporting Services dão suporte a 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 de corpo da mensagem de solicitação HTTP:

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

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

    • Um código de status HTTP, que varia de códigos de sucesso 2xx a códigos de erro 4xx ou 5xx. Como alternativa, o sistema pode retornar um código de status definido pelo serviço, conforme indicado na documentação da API.
    • Campos de cabeçalho adicionais opcionais, conforme necessário, para dar suporte à resposta da solicitação, como um cabeçalho de resposta Content-type.

  • Campos opcionais de corpo da mensagem de resposta HTTP:

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

Documentação da API

Uma API REST moderna necessita de uma documentação de API moderna. Uma API REST é criada na especificação OpenAPI, que também é chamada de especificação swagger. A documentação da API REST do Servidor de Relatórios do Power BI está disponível no Microsoft Learn.

Testar chamadas de API

Se precisar de uma ferramenta para testar mensagens de solicitação/resposta HTTP, o Fiddler é um proxy Web de depuração gratuito que pode interceptar as solicitações REST, facilitando o diagnóstico de mensagens de solicitação/resposta HTTP.

Conteúdo relacionado