Desenvolver com as APIs REST do Servidor de Relatórios do Power BI

O Servidor de Relatórios do Power BI é compatível com as 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), que fornecem acesso de criação, recuperação, atualização ou exclusão para recursos em um servidor de relatório.

A API REST fornece acesso por meio de programação aos objetos em um catálogo do Servidor de Relatórios do Power BI. Exemplos de objetos são pastas, relatórios, KPIs, fontes de dados, conjuntos de dados, planos de atualização, assinaturas e muito mais. Usando a API REST, você pode, por exemplo, 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. Exemplos de como trabalhar com objetos são carregar um relatório, executar um plano de atualização, excluir uma pasta e assim por diante.

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 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, que consiste em {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Embora o URI de solicitação seja incluído no cabeçalho da mensagem de solicitação, chamamos o URI separadamente aqui porque a maioria das linguagens ou estruturas exige que ele seja passado separadamente da mensagem de solicitação.

    • Esquema de URI: indica o protocolo usado para transmitir a solicitação. Por exemplo, http ou https.
    • Host de 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.
    • Caminho do recurso: 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: CatalogItems(01234567-89ab-cdef-0123-456789abcdef)/Properties pode ser usado para obter as propriedades especificadas para o CatalogItem.
    • Cadeia de consulta (opcional): fornece parâmetros adicionais simples, como a versão de API ou os critérios de seleção de recursos.
  • Campos de cabeçalho da mensagem de solicitação HTTP:

    • Um método HTTP obrigatório (também conhecido como uma operação ou um verbo), que indica ao serviço que tipo de operação está sendo solicitada. 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, para dar suporte à operação de URI e HTTP. Por exemplo, as operações POST contêm objetos codificado em MIME 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, um código de status definido pelo serviço pode ser retornado, 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. A API REST baseia-se na especificação OpenAPI (também conhecido como especificação do Swagger) e a documentação está disponível no Microsoft Learn.

Testando chamadas à API

Uma ferramenta para testar as mensagens de solicitação/resposta HTTP é o Fiddler. 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.

Examine as APIs disponíveis no Microsoft Learn.

As amostras estão disponíveis no GitHub. A amostra inclui um aplicativo HTML5 baseado em TypeScript, React e Webpack, juntamente com um exemplo do PowerShell.

Mais perguntas? Experimente perguntar à Comunidade do Power BI