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

O Servidor de Relatórios do Power BI 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), 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 programático 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 na 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.

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 da solicitação, que consiste em: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Embora o URI da solicitação esteja incluído no cabeçalho da mensagem de solicitação, nós o chamamos separadamente aqui porque a maioria dos idiomas ou estruturas exige que você a passe 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 em que o ponto de extremidade do 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 na determinação da 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 caracteres de consulta (opcional): fornece outros parâmetros simples, como a versão da 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), que informa ao serviço qual tipo de operação você está solicitando. As APIs REST do Reporting Services dão suporte aos métodos DELETE, GET, HEAD, PUT, POST e PATCH.
  • Outros campos de cabeçalho opcionais, conforme exigido pelo URI e pelo método HTTP especificados.

• Campos opcionais do corpo da mensagem de solicitação HTTP, para dar suporte à operação URI e HTTP. Por exemplo, as operações POST contêm objetos codificados em MIME que são passados como parâmetros complexos. Para operações POST ou PUT, o tipo de codificação MIME para o corpo também deve ser especificado no cabeçalho da Content-type solicitação. Alguns serviços exigem que você use um tipo MIME específico, como application/json.

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

  • Um código de status HTTP, que varia de códigos de êxito 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.
  • Outros campos de cabeçalho opcionais, conforme necessário para dar suporte à resposta da solicitação, como um cabeçalho de resposta Content-type.

• Campos opcionais do corpo da mensagem de resposta HTTP:

  • 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 Content-type resposta.

Documentação da API

Uma API REST moderna exige a documentação moderna da API. A API REST baseia-se na especificação OpenAPI (também conhecida como especificação do swagger) e a documentação está disponível no Microsoft Learn.

Testando chamadas à API

Uma ferramenta para testar mensagens de solicitação/resposta HTTP é o Fiddler. O Fiddler é um proxy de depuração da Web gratuito que pode interceptar suas solicitações REST, facilitando o diagnóstico das mensagens de solicitação/resposta HTTP.

Conteúdo relacionado

Examine as APIs disponíveis no Microsoft Learn.

Os exemplos estão disponíveis no GitHub. O exemplo inclui um aplicativo HTML5 criado em TypeScript, React e webpack, juntamente com um exemplo do PowerShell.

Mais perguntas? Tente perguntar à Comunidade do Power BI