Desenvolver com as APIs REST do Servidor de Relatórios do Power BIDevelop with the REST APIs for Power BI Report Server

O Servidor de Relatórios do Power BI é compatível com as APIs REST (Transferência de Estado Representacional).Power BI Report Server support Representational State Transfer (REST) APIs. As APIs REST são pontos de extremidade de serviço compatíveis com um conjunto de operações de HTTP (métodos), que fornecem acesso à criação, à recuperação, à atualização ou à exclusão para recursos em um servidor de relatório.The REST APIs are service endpoints that support a set of HTTP operations (methods), which provide create, retrieve, update, or delete access for resources within a report server.

A API REST fornece acesso por meio de programação aos objetos em um catálogo do Servidor de Relatórios do Power BI.The REST API provides programmatic access to the objects in a Power BI Report Server catalog. Os exemplos de objetos incluem pastas, relatórios, KPIs, fontes de dados, conjuntos de dados, planos de atualização, assinaturas e muito mais.Examples of objects are folders, reports, KPIs, data sources, datasets, refresh plans, subscriptions, and more. Ao usar a API REST, é possível, por exemplo, navegar na hierarquia de pastas, descobrir o conteúdo de uma pasta ou baixar uma definição de relatório.Using the REST API, you can, for example, navigate the folder hierarchy, discover the contents of a folder, or download a report definition. Você também pode criar, atualizar e excluir objetos.You can also create, update, and delete objects. Os exemplos de como trabalhar com objetos incluem carregar um relatório, executar um plano de atualização, excluir uma pasta e assim por diante.Examples of working with objects are upload a report, execute a refresh plan, delete a folder, and so on.

Componentes de uma solicitação/resposta da API RESTComponents of a REST API request/response

Um par solicitação/resposta da API REST pode ser dividido em cinco componentes:A REST API request/response pair can be separated into five components:

  • O URI da solicitação, que consiste em: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}.The request URI, which consists of: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}. Embora o URI da solicitação seja incluído no cabeçalho da mensagem de solicitação, vamos chamá-lo separadamente aqui porque a maioria das linguagens ou das estruturas exige que ele seja passado separadamente da mensagem de solicitação.Although the request URI is included in the request message header, we call it out separately here because most languages or frameworks require you to pass it separately from the request message.

    • Esquema de URI: indica o protocolo usado para transmitir a solicitação.URI scheme: Indicates the protocol used to transmit the request. Por exemplo, http ou https.For example, http or https.
    • URI do host: especifica o nome de domínio ou o endereço IP do servidor, em que o ponto de extremidade de serviço REST está hospedado, como myserver.contoso.com.URI host: Specifies the domain name or IP address of the server where the REST service endpoint is hosted, such as 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.Resource path: Specifies the resource or resource collection, which may include multiple segments used by the service in determining the selection of those resources. Por exemplo: CatalogItems(01234567-89ab-cdef-0123-456789abcdef)/Properties pode ser usado para obter as propriedades especificadas para o CatalogItem.For example: CatalogItems(01234567-89ab-cdef-0123-456789abcdef)/Properties can be used to get the specified properties for the CatalogItem.
    • Cadeia de caracteres de consulta (opcional): fornece parâmetros adicionais simples, como os critérios de seleção de recursos ou a versão da API.Query string (optional): Provides additional simple parameters, such as the API version or resource selection criteria.
  • Campos do cabeçalho da mensagem de solicitação HTTP:HTTP request message header fields:

    • Um método HTTP necessário (também conhecido como operação ou verbo), que informa o serviço que tipo de operação você está solicitando.A required HTTP method (also known as an operation or verb), which tells the service what type of operation you are requesting. As APIs REST do Reporting Services são compatíveis com os métodos DELETE, GET, HEAD, PUT, POST e PATCH.Reporting Services REST APIs support DELETE, GET, HEAD, PUT, POST, and PATCH methods.
    • Campos de cabeçalho adicionais opcionais, conforme exigido pelo método HTTP e o URI especificados.Optional additional header fields, as required by the specified URI and HTTP method.
  • Campos do corpo da mensagem de solicitação HTTP, para fins de compatibilidade com a operação HTTP e URI.Optional HTTP request message body fields, to support the URI and HTTP operation. Por exemplo, as operações POST contêm objetos codificados em MIME passados como parâmetros complexos.For example, POST operations contain MIME-encoded objects that are passed as complex parameters. Para as operações POST ou PUT, o tipo de codificação MIME para o corpo também deve ser especificado no cabeçalho da solicitação Content-type.For POST or PUT operations, the MIME-encoding type for the body should be specified in the Content-type request header as well. Alguns serviços exigem que você use um tipo MIME específico, como application/json.Some services require you to use a specific MIME type, such as application/json.
  • Campos do cabeçalho da mensagem de resposta HTTP:HTTP response message header fields:

    • Um código de status HTTP, com intervalo de 2xx códigos de êxito e 4xx ou 5xx códigos de erro.An HTTP status code, ranging from 2xx success codes to 4xx or 5xx error codes. Como alternativa, um código de status definido pelo serviço pode ser retornado, conforme indicado na documentação da API.Alternatively, a service-defined status code may be returned, as indicated in the API documentation.
    • Campos de cabeçalho adicionais opcionais, conforme necessário para oferecer compatibilidade com a resposta da solicitação, como um cabeçalho de resposta Content-type.Optional additional header fields, as required to support the request's response, such as a Content-type response header.
  • Campos do corpo da mensagem de resposta HTTP opcionais:Optional HTTP response message body fields:

    • Objetos de resposta codificados em MIME são retornados no corpo da resposta HTTP, como uma resposta de um método GET retornando dados.MIME-encoded response objects are returned in the HTTP response body, such as a response from a GET method that is returning data. Normalmente, esses objetos são retornados em um formato estruturado, como JSON ou XML, conforme indicado pelo cabeçalho de resposta Content-type.Typically, these objects are returned in a structured format such as JSON or XML, as indicated by the Content-type response header.

Documentação da APIAPI documentation

Uma API REST moderna necessita de uma documentação de API moderna.A modern REST API calls for modern API documentation. A API REST é baseada na especificação OpenAPI (também conhecida comoThe REST API is built on the OpenAPI specification (a.k.a. a especificação swagger) e a documentação está disponível no SwaggerHub.the swagger specification) and documentation is available on SwaggerHub. Além da documentação da API, o SwaggerHub ajuda a gerar uma biblioteca de clientes na linguagem desejada: JavaScript, TypeScript, C#, Java, Python, Ruby e muito mais.Beyond documenting the API, SwaggerHub helps generate a client library in the language of choice – JavaScript, TypeScript, C#, Java, Python, Ruby, and more.

Testando chamadas à APITesting API calls

O Fiddler é uma ferramenta para testar mensagens de solicitação/resposta HTTP.A tool for testing HTTP request/response messages is Fiddler. O Fiddler é uma proxy de depuração Web gratuito que pode interceptar solicitações REST, o que facilita o diagnóstico das mensagens de solicitação/resposta HTTP.Fiddler is a free web debugging proxy that can intercept your REST requests, making it easy to diagnose the HTTP request/ response messages.

Próximas etapasNext steps

Examinar as APIs disponíveis no SwaggerHub.Review the available APIs over on SwaggerHub.

Os exemplos estão disponíveis no GitHub.Samples are available on GitHub. O exemplo inclui um aplicativo HTML5 baseado no TypeScript, no React e no webpack, juntamente com um exemplo do PowerShell.The sample includes an HTML5 app built on TypeScript, React, and webpack along with a PowerShell example.

Mais perguntas?More questions? Experimente perguntar à Comunidade do Power BITry asking the Power BI Community