Como Chamar uma API pelo PowerShell

Pessoal.

Esta semana nos deparamos com um problema, como fazer a chamada de uma API pelo PowerShell?

Isto foi necessário para um caso específico onde precisávamos de um script para colocar em um serviço de coleta de dados interno para nossos clientes, por este motivo não foi feito um ETL ou um executável em .Net para atender a esta necessidade.

Vamos lá, para exemplo vou usar a API do Azure que retorna os dados de consumo de espaço do Azure SQL Database.

A titulo de conhecimento, o Azure tem várias APIs que retorna dados e informações dos seus serviços, neste site tem a documentação de cada uma das APIs: Azure SQL Database REST API reference | Microsoft Docs para este artigo vamos usar especificamente esta API: Database Usages – List By Database – REST API (Azure SQL Database) | Microsoft Docs, que retorna informações de espaço usado e limite de espaço contratado pelo Azure SQL Database. 

A chamada desta API em específico é bem simples, deve ser informado 5 valores:

1. Subscription: O ID da Subscription;
2. ResourceGroup: O nome do grupo de recurso;
3. Servers: O nome do servidor do SQL Database;
4. Database: O nome do SQL Database;
5. Token: O token de autenticação que é renovado frequentemente.

Os 4 primeiros itens são informados na URL da API, segue abaixo um print do Postman com a chamada da API.

O token é informado no Header da chamada passando como uma Autenticação do tipo Bearer.

E o resultado é um JSON com as informações que desejamos:

{
"value": [ 
  {
   "properties": {
    "displayName": "Database Size", 
    "currentValue": 29360128.0, 
    "limit": 34359738368.0, 
    "unit": "Bytes"
   },
   "id": "/subscriptions/7*******-f***-4***-8****- 0***********/resourceGroups/D***/providers/Microsoft.Sql/servers/srvsql*****/databases/SQL****/usages/database_size",
   "name": "database_size",
   "type": "Microsoft.Sql/servers/databases/usages" 
   },
   {
"properties": {
   "displayName": "Database Allocated Size", 
   "currentValue": 33554432.0,
   "limit": 34359738368.0,
   "unit": "Bytes"
   },
   "id": "/subscriptions/7*******-f***-4***-8****- 0***********/resourceGroups/D***/providers/Microsoft.Sql/servers/srvsql*****/databases/SQL****/usages/database_size"",
   "name": "database_allocated_size",
   "type": "Microsoft.Sql/servers/databases/usages" 
  }
 ]
}

Certo, pelo Postman a API retornou, agora vamos ao script em PowerShell. Vamos explicar parte por parte do script para ser o mais didático possível.

Primeira Parte – Conectar na subscription

Como já citado a API necessita de um Token para autenticação e este Token tem uma validade razoavelmente curta, por este motivo incluímos no script a geração do token, assim para cada conexão à API um novo token é gerado isso evita que o ele expire entre uma conexão e outra.

Abaixo segue o código desta primeira parte:

# importa o módulo Az na sessão de execução do script
# Install-module az
Import-module Az
# Gera token de acesso a API
$SubscriptionID = '7****-f**-4**-8****-0****'
$SQLServer = 'srvsql****'
$SqlDatabase = 'SQL****'
$ResourceGroup = 'D*****'
$credential = Import-Clixml 'C:\temp\Credential.xml'
Connect-AzAccount -Credential $credential -Subscription $SubscriptionID

Linha 2: O comando install-module só é necessário se o módulo do Az ainda não tenha sido instalado, se já foi pode ser ignorado;

Linha 3: esta é obrigatório, pois ele carrega na sessão do Power Shell os comandos e recursos necessários do módulo AZ;

Linha 5, 6, 7 e 8: São definições de variáveis que depois serão usadas na conexão com a API;

Linha 9: importa a credencial. Esta credencial deve ser um e-mail e senha que tenha acesso ao grupo de recurso do SQL Database, por este motivo foi feito desta forma, assim o usuário e senha não ficam abertos no script, e mesmo que alguém tenha acesso ao arquivo XML a senha esta criptografada. Podemos falar mais sobre este assunto em outro artigo;

Linha 10: Conectamos na Subscription do Azure, informando o Id da Subscription e a credencial.

Segunda Parte – Gerar o token

$azContext = Get-AzContext
azProfile =[Microsoft.Azure.Commands.Common.Authentication.Abstractions.AzureRmProfileProvider]::Instance.Profile
$profileClient = New-Object -TypeName Microsoft.Azure.Commands.ResourceManager.Common.RMProfileClient -ArgumentList ($azProfile)
$token =$profileClient.AcquireAccessToken($azContext.Subscription.TenantId)

Linha 11: Vamos atribuir a uma variável o Contexto da Subscription que conectamos na Linha 10;

Linha 12: Criamos uma variável de Profile, a partir da Classe de Authtentication;

Linha 13: Atribuímos a um novo objeto do tipo RMProfileCliente usando o profile criado na Linha 12;

Linha 14: Usamos o objeto da linha 13 para gerar o Access Token passando por parâmetro o TenantId do objeto criado na Linha 12.

Terceira Parte – Montar o Header da chamada da API

 #Monta o Header para acesso a API do SQL Database
$authHeader = @{'Content-Type'='application/json' 
'Authorization'='Bearer ' + $token.AccessToken
}

Linha 16: Criarmos um array que será usado na chamada da API, este array defini dois parâmetros o Content-type que define que o retorno será um JSON e a autorização que será feita pelo tolken do tipo Bearer.

Quarta Parte – Conecta na API

# Conecta a API e retorna os dados do SQL Database
$URI=https://management.azure.com/subscriptions/$SubscriptionID/resourceGroups/$ResourceGroup/providers/Microsoft.Sql/servers/$SQLServer/databas es/$SqlDatabase/usages?api-version=2021-11-01"
 $Parameters = @{
 Method = "GET"
 Uri = $URI
 Headers = $authHeader
 }
$result = Invoke-RestMethod @Parameters
$result|ConvertTo-Json |Out-File C:\temp\AzureSQL.json

Nesta quarta parte vamos efetivamente conectar e retornar os dados da API.

Linha 21: Montagem da URL da API, como anteriormente definimos as variáveis como os valores, neste item concatenamos ao URL com as variáveis como o ID da Subscription, nome do servidor, nome banco de dados etc.

Linha 22: Criamos outro Array, este para os parâmetros que será usado pela classe Invoke- RestMethod, neste Array vamos definir que será uma chamada do tipo GET, vamos definir a URL, os Headers, que já inclui o Token.

Linha 27: Temos a chamada propriamente dita, onde usamos o comando Invoke-RestMethod passando como parâmetros o Array definido na linha 22. O retorno da API será gravado na variável $result.

Linha 28: Para finalizar então, o valor da variável $result é gravado em um arquivo assim temos o retorno da API em um arquivo para ser consumido. Claro que este resultado também pode ser deserializado em uma classe, se necessário.

Pessoal, para finalizar espero que tenham gostado do artigo e que sejam úteis para vocês. O exemplo usado neste artigo foi feito no Power Shell 7, que é baseado no .Net Core, então para quem conhece e programa em .Net deve ter sido bem fácil de entender. O script completo adicionaremos no Github.

Até o próximo artigo.