Instruções da API REST de monitoramento do AzureAzure Monitoring REST API walkthrough

Observação

Este artigo foi atualizado para usar o novo módulo Az do Azure PowerShell.This article has been updated to use the new Azure PowerShell Az module. Você ainda pode usar o módulo AzureRM, que continuará a receber as correções de bugs até pelo menos dezembro de 2020.You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. Para saber mais sobre o novo módulo Az e a compatibilidade com o AzureRM, confira Apresentação do novo módulo Az do Azure PowerShell.To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. Para obter instruções de instalação do módulo Az, confira Instalar o Azure PowerShell.For Az module installation instructions, see Install Azure PowerShell.

Este artigo mostra como executar autenticação para que o seu código possa usar a referência de API REST do Monitor do Microsoft Azure.This article shows you how to perform authentication so your code can use the Microsoft Azure Monitor REST API Reference.

A API Azure Monitor possibilita recuperar programaticamente as definições de métrica padrão disponíveis, a granularidade e os valores de métrica.The Azure Monitor API makes it possible to programmatically retrieve the available default metric definitions, granularity, and metric values. Os dados podem ser salvos em um armazenamento de dados separado, como o banco de dados SQL do Azure, Azure Cosmos DB ou Azure Data Lake.The data can be saved in a separate data store such as Azure SQL Database, Azure Cosmos DB, or Azure Data Lake. A partir daí, uma análise adicional pode ser executada conforme necessário.From there additional analysis can be performed as needed.

Além de trabalhar com vários pontos de dados de métrica, a API do monitor também torna possível listar as regras de alerta, exibir logs de atividades e muito mais.Besides working with various metric data points, the Monitor API also makes it possible to list alert rules, view activity logs, and much more. Para obter uma lista completa das operações disponíveis, consulte a referência da API REST do Monitor do Microsoft Azure.For a full list of available operations, see the Microsoft Azure Monitor REST API Reference.

Autenticando solicitações de Azure MonitorAuthenticating Azure Monitor requests

A primeira etapa é autenticar a solicitação.The first step is to authenticate the request.

Todas as tarefas executadas em relação à API de Azure Monitor usam o modelo de autenticação Azure Resource Manager.All the tasks executed against the Azure Monitor API use the Azure Resource Manager authentication model. Portanto, todas as solicitações devem ser autenticadas com Azure Active Directory (Azure AD).Therefore, all requests must be authenticated with Azure Active Directory (Azure AD). Uma abordagem para autenticar o aplicativo cliente é criar uma entidade de serviço do Azure AD e recuperar o token de autenticação (JWT).One approach to authenticate the client application is to create an Azure AD service principal and retrieve the authentication (JWT) token. O exemplo de script a seguir demonstra como criar uma entidade de serviço do Azure AD por meio do PowerShell.The following sample script demonstrates creating an Azure AD service principal via PowerShell. Para obter instruções mais detalhadas, consulte a documentação sobre como usar o Azure PowerShell para criar uma entidade de serviço para acessar recursos.For a more detailed walk-through, refer to the documentation on using Azure PowerShell to create a service principal to access resources. Também é possível criar uma entidade de serviço por meio do portal do Azure.It is also possible to create a service principal via the Azure portal.

$subscriptionId = "{azure-subscription-id}"
$resourceGroupName = "{resource-group-name}"

# Authenticate to a specific Azure subscription.
Connect-AzAccount -SubscriptionId $subscriptionId

# Password for the service principal
$pwd = "{service-principal-password}"
$secureStringPassword = ConvertTo-SecureString -String $pwd -AsPlainText -Force

# Create a new Azure AD application
$azureAdApplication = New-AzADApplication `
                        -DisplayName "My Azure Monitor" `
                        -HomePage "https://localhost/azure-monitor" `
                        -IdentifierUris "https://localhost/azure-monitor" `
                        -Password $secureStringPassword

# Create a new service principal associated with the designated application
New-AzADServicePrincipal -ApplicationId $azureAdApplication.ApplicationId

# Assign Reader role to the newly created service principal
New-AzRoleAssignment -RoleDefinitionName Reader `
                          -ServicePrincipalName $azureAdApplication.ApplicationId.Guid

Para consultar a API de Azure Monitor, o aplicativo cliente deve usar a entidade de serviço criada anteriormente para autenticar.To query the Azure Monitor API, the client application should use the previously created service principal to authenticate. O exemplo de script do PowerShell a seguir mostra uma abordagem, usando o biblioteca de autenticação do Active Directory (Adal) para obter o token de autenticação JWT.The following example PowerShell script shows one approach, using the Active Directory Authentication Library (ADAL) to obtain the JWT authentication token. O token JWT é passado como parte de um parâmetro de autorização HTTP em solicitações para a API REST do Azure Monitor.The JWT token is passed as part of an HTTP Authorization parameter in requests to the Azure Monitor REST API.

$azureAdApplication = Get-AzADApplication -IdentifierUri "https://localhost/azure-monitor"

$subscription = Get-AzSubscription -SubscriptionId $subscriptionId

$clientId = $azureAdApplication.ApplicationId.Guid
$tenantId = $subscription.TenantId
$authUrl = "https://login.microsoftonline.com/${tenantId}"

$AuthContext = [Microsoft.IdentityModel.Clients.ActiveDirectory.AuthenticationContext]$authUrl
$cred = New-Object -TypeName Microsoft.IdentityModel.Clients.ActiveDirectory.ClientCredential -ArgumentList ($clientId, $pwd)

$result = $AuthContext.AcquireTokenAsync("https://management.core.windows.net/", $cred).GetAwaiter().GetResult()

# Build an array of HTTP header values
$authHeader = @{
'Content-Type'='application/json'
'Accept'='application/json'
'Authorization'=$result.CreateAuthorizationHeader()
}

Após a autenticação, as consultas podem ser executadas em relação à API REST do Azure Monitor.After authenticating, queries can then be executed against the Azure Monitor REST API. Há duas consultas úteis:There are two helpful queries:

  1. Listar as definições de métrica para um recursoList the metric definitions for a resource
  2. Recuperar os valores de métricaRetrieve the metric values

Observação

Para obter informações adicionais sobre como autenticar com a API REST do Azure, consulte a referência da API REST do Azure.For additional information on authenticating with the Azure REST API, please refer to the Azure REST API Reference.

Recuperar as definições de métrica (API multidimensional)Retrieve Metric Definitions (Multi-Dimensional API)

Use a API REST de definições da Métrica do Azure Monitor para acessar a lista de métricas disponíveis para um serviço.Use the Azure Monitor Metric definitions REST API to access the list of metrics that are available for a service.

Método: GETMethod: GET

URI de solicitação: https: / /management. Azure.com/subscriptions/ {SubscriptionId} /resourceGroups/ {resourceGroupName} /Providers/ {resourceProviderNamespace} / {ResourceType} / {resourceName} /Providers/Microsoft.insights/metricDefinitions? API-Version = {apiVersion}Request URI: https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}/providers/microsoft.insights/metricDefinitions?api-version={apiVersion}

Por exemplo, para recuperar as definições de métrica para uma conta de armazenamento do Azure, a solicitação seria exibida da seguinte maneira:For example, to retrieve the metric definitions for an Azure Storage account, the request would appear as follows:

$request = "https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metricDefinitions?api-version=2018-01-01"

Invoke-RestMethod -Uri $request `
                  -Headers $authHeader `
                  -Method Get `
                  -OutFile ".\contosostorage-metricdef-results.json" `
                  -Verbose

Observação

Para recuperar as definições de métrica usando a API REST de métricas de Azure Monitor multidimensionais, use "2018-01-01" como a versão de API.To retrieve metric definitions using the multi-dimensional Azure Monitor metrics REST API, use "2018-01-01" as the API version.

O corpo de resposta JSON resultante seria semelhante ao exemplo a seguir: (Observe que a segunda métrica tem dimensões)The resulting JSON response body would be similar to the following example: (Note that the second metric has dimensions)

{
    "value": [
        {
            "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metricdefinitions/UsedCapacity",
            "resourceId": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage",
            "namespace": "Microsoft.Storage/storageAccounts",
            "category": "Capacity",
            "name": {
                "value": "UsedCapacity",
                "localizedValue": "Used capacity"
            },
            "isDimensionRequired": false,
            "unit": "Bytes",
            "primaryAggregationType": "Average",
            "supportedAggregationTypes": [
                "Total",
                "Average",
                "Minimum",
                "Maximum"
            ],
            "metricAvailabilities": [
                {
                    "timeGrain": "PT1H",
                    "retention": "P93D"
                },
                {
                    "timeGrain": "PT6H",
                    "retention": "P93D"
                },
                {
                    "timeGrain": "PT12H",
                    "retention": "P93D"
                },
                {
                    "timeGrain": "P1D",
                    "retention": "P93D"
                }
            ]
        },
        {
            "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metricdefinitions/Transactions",
            "resourceId": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage",
            "namespace": "Microsoft.Storage/storageAccounts",
            "category": "Transaction",
            "name": {
                "value": "Transactions",
                "localizedValue": "Transactions"
            },
            "isDimensionRequired": false,
            "unit": "Count",
            "primaryAggregationType": "Total",
            "supportedAggregationTypes": [
                "Total"
            ],
            "metricAvailabilities": [
                {
                    "timeGrain": "PT1M",
                    "retention": "P93D"
                },
                {
                    "timeGrain": "PT5M",
                    "retention": "P93D"
                },
                {
                    "timeGrain": "PT15M",
                    "retention": "P93D"
                },
                {
                    "timeGrain": "PT30M",
                    "retention": "P93D"
                },
                {
                    "timeGrain": "PT1H",
                    "retention": "P93D"
                },
                {
                    "timeGrain": "PT6H",
                    "retention": "P93D"
                },
                {
                    "timeGrain": "PT12H",
                    "retention": "P93D"
                },
                {
                    "timeGrain": "P1D",
                    "retention": "P93D"
                }
            ],
            "dimensions": [
                {
                    "value": "ResponseType",
                    "localizedValue": "Response type"
                },
                {
                    "value": "GeoType",
                    "localizedValue": "Geo type"
                },
                {
                    "value": "ApiName",
                    "localizedValue": "API name"
                }
            ]
        },
        ...
    ]
}

Recuperar valores de dimensão (API multidimensional)Retrieve Dimension Values (Multi-Dimensional API)

Depois que as definições de métrica disponíveis são conhecidas, pode haver algumas métricas que têm dimensões.Once the available metric definitions are known, there may be some metrics that have dimensions. Antes de consultar a métrica, talvez você queira descobrir qual é o intervalo de valores de uma dimensão.Before querying for the metric you may want to discover what the range of values a dimension has. Com base nesses valores de dimensão, você pode optar por filtrar ou segmentar as métricas com base nos valores de dimensão ao consultar as métricas.Based on these dimension values you can then choose to filter or segment the metrics based on dimension values while querying for metrics. Use a API REST de métricas Azure monitor para conseguir isso.Use the Azure Monitor Metrics REST API to achieve this.

Use o nome da métrica ' value ' (não o ' localizador ') para quaisquer solicitações de filtragem.Use the metric’s name ‘value’ (not the ‘localizedValue’) for any filtering requests . Se nenhum filtro for especificado, a métrica padrão será retornada.If no filters are specified, the default metric is returned. O uso dessa API só permite que uma dimensão tenha um filtro curinga.The usage of this API only allows one dimension to have a wildcard filter.

Observação

Para recuperar valores de dimensão usando a API REST do Azure Monitor, use "2018-01-01" como a versão da API.To retrieve dimension values using the Azure Monitor REST API, use "2018-01-01" as the API version.

Método: GETMethod: GET

URI da solicitação: https ://Management.Azure.com/subscriptions/ {Subscription-ID} /resourceGroups/ {nome-do-grupo-de-recursos} /Providers/ {Resource-Provider-namespace} / {Resource-Type} / {nome-do-recurso} /Providers/Microsoft.insights/Metrics de métricas = {Metric} & TimeSpan = {starttime/EndTime} & $Filter = {filtro} & ResultType = metadados & API-Version = { apiVersion}Request URI: https://management.azure.com/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/{resource-provider-namespace}/{resource-type}/{resource-name}/providers/microsoft.insights/metrics?metricnames={metric}&timespan={starttime/endtime}&$filter={filter}&resultType=metadata&api-version={apiVersion}

Por exemplo, para recuperar a lista de valores de dimensão que foram emitidos para a ' dimensão de nome da API ' para a métrica ' transações ', em que a dimensão geotipo = ' primário ' durante o intervalo de tempo especificado, a solicitação seria a seguinte:For example, to retrieve the list of dimension values that were emitted for the 'API Name dimension' for the 'Transactions' metric, where the GeoType dimension = 'Primary' during the specified time range, the request would be as follows:

$filter = "APIName eq '*' and GeoType eq 'Primary'"
$request = "https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metrics?metricnames=Transactions&timespan=2018-03-01T00:00:00Z/2018-03-02T00:00:00Z&resultType=metadata&`$filter=${filter}&api-version=2018-01-01"
Invoke-RestMethod -Uri $request `
    -Headers $authHeader `
    -Method Get `
    -OutFile ".\contosostorage-dimension-values.json" `
    -Verbose

O corpo de resposta JSON resultante seria semelhante ao exemplo a seguir:The resulting JSON response body would be similar to the following example:

{
  "timespan": "2018-03-01T00:00:00Z/2018-03-02T00:00:00Z",
  "value": [
    {
      "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/Microsoft.Insights/metrics/Transactions",
      "type": "Microsoft.Insights/metrics",
      "name": {
        "value": "Transactions",
        "localizedValue": "Transactions"
      },
      "unit": "Count",
      "timeseries": [
        {
          "metadatavalues": [
            {
              "name": {
                "value": "apiname",
                "localizedValue": "apiname"
              },
              "value": "DeleteBlob"
            }
          ]
        },
        {
          "metadatavalues": [
            {
              "name": {
                "value": "apiname",
                "localizedValue": "apiname"
              },
              "value": "SetBlobProperties"
            }
          ]
        },
        ...
      ]
    }
  ],
  "namespace": "Microsoft.Storage/storageAccounts",
  "resourceregion": "eastus"
}

Recuperar valores de métrica (API multidimensional)Retrieve Metric Values (Multi-Dimensional API)

Depois que as definições de métricas disponíveis e os possíveis valores de dimensão forem conhecidos, será possível recuperar os valores de métrica relacionados.Once the available metric definitions and possible dimension values are known, it is then possible to retrieve the related metric values. Use a API REST de métricas Azure monitor para conseguir isso.Use the Azure Monitor Metrics REST API to achieve this.

Use o nome da métrica ' value ' (não o ' localizador ') para quaisquer solicitações de filtragem.Use the metric’s name ‘value’ (not the ‘localizedValue’) for any filtering requests. Se nenhum filtro de dimensão for especificado, a métrica Agregada acumulada será retornada.If no dimension filters are specified, the rolled up aggregated metric is returned. Se uma consulta de métrica retornar várias séries temporais, você poderá usar os parâmetros de consulta ' top ' e ' OrderBy ' para retornar uma lista ordenada limitada de timeseries.If a metric query returns multiple timeseries, then you can use the 'Top' and 'OrderBy' query parameters to return an limited ordered list of timeseries.

Observação

Para recuperar valores de métrica multidimensionais usando a API REST do Azure Monitor, use "2018-01-01" como a versão da API.To retrieve multi-dimensional metric values using the Azure Monitor REST API, use "2018-01-01" as the API version.

Método: GETMethod: GET

URI da solicitação: https://management.azure.com/subscriptions/ {Subscription-ID} /resourceGroups/ {nome-do-grupo-de-recursos} /Providers/ {Resource-Provider-namespace} / {tipo de recurso} / {nome-do-recurso} /Providers/ Microsoft. insights/métricas? métricanames = {métrica} & TimeSpan = {StartTime/endtime} & $Filter = {filtro} & intervalo = {timegranular} & agregação = {aggreation} & API-Version = {apiVersion}Request URI: https://management.azure.com/subscriptions/*{subscription-id}*/resourceGroups/*{resource-group-name}*/providers/*{resource-provider-namespace}*/*{resource-type}*/*{resource-name}*/providers/microsoft.insights/metrics?metricnames=*{metric}*&timespan=*{starttime/endtime}*&$filter=*{filter}*&interval=*{timeGrain}*&aggregation=*{aggreation}*&api-version=*{apiVersion}*

Por exemplo, para recuperar as três principais APIs, em valor decrescente, pelo número de ' Transactions ' durante um intervalo de 5 minutos, em que GeotType era ' Primary ', a solicitação seria a seguinte:For example, to retrieve the top 3 APIs, in descending value, by the number of 'Transactions' during a 5 min range, where the GeotType was 'Primary', the request would be as follows:

$filter = "APIName eq '*' and GeoType eq 'Primary'"
$request = "https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/microsoft.insights/metrics?metricnames=Transactions&timespan=2018-03-01T02:00:00Z/2018-03-01T02:05:00Z&`$filter=${filter}&interval=PT1M&aggregation=Total&top=3&orderby=Total desc&api-version=2018-01-01"
Invoke-RestMethod -Uri $request `
    -Headers $authHeader `
    -Method Get `
    -OutFile ".\contosostorage-metric-values.json" `
    -Verbose

O corpo de resposta JSON resultante seria semelhante ao exemplo a seguir:The resulting JSON response body would be similar to the following example:

{
  "cost": 0,
  "timespan": "2018-03-01T02:00:00Z/2018-03-01T02:05:00Z",
  "interval": "PT1M",
  "value": [
    {
      "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/ContosoStorage/providers/Microsoft.Insights/metrics/Transactions",
      "type": "Microsoft.Insights/metrics",
      "name": {
        "value": "Transactions",
        "localizedValue": "Transactions"
      },
      "unit": "Count",
      "timeseries": [
        {
          "metadatavalues": [
            {
              "name": {
                "value": "apiname",
                "localizedValue": "apiname"
              },
              "value": "GetBlobProperties"
            }
          ],
          "data": [
            {
              "timeStamp": "2017-09-19T02:00:00Z",
              "total": 2
            },
            {
              "timeStamp": "2017-09-19T02:01:00Z",
              "total": 1
            },
            {
              "timeStamp": "2017-09-19T02:02:00Z",
              "total": 3
            },
            {
              "timeStamp": "2017-09-19T02:03:00Z",
              "total": 7
            },
            {
              "timeStamp": "2017-09-19T02:04:00Z",
              "total": 2
            }
          ]
        },
        ...
      ]
    }
  ],
  "namespace": "Microsoft.Storage/storageAccounts",
  "resourceregion": "eastus"
}

Recuperar definições de métricaRetrieve metric definitions

Use a API REST de definições da Métrica do Azure Monitor para acessar a lista de métricas disponíveis para um serviço.Use the Azure Monitor Metric definitions REST API to access the list of metrics that are available for a service.

Método: GETMethod: GET

URI de solicitação: https: / /management. Azure.com/subscriptions/ {SubscriptionId} /resourceGroups/ {resourceGroupName} /Providers/ {resourceProviderNamespace} / {ResourceType} / {resourceName} /Providers/Microsoft.insights/metricDefinitions? API-Version = {apiVersion}Request URI: https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}/providers/microsoft.insights/metricDefinitions?api-version={apiVersion}

Por exemplo, para recuperar as definições de métrica para um aplicativo lógico do Azure, a solicitação seria exibida da seguinte maneira:For example, to retrieve the metric definitions for an Azure Logic App, the request would appear as follows:

$request = "https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Logic/workflows/ContosoTweets/providers/microsoft.insights/metricDefinitions?api-version=2016-03-01"

Invoke-RestMethod -Uri $request `
                  -Headers $authHeader `
                  -Method Get `
                  -OutFile ".\contosotweets-metricdef-results.json" `
                  -Verbose

Observação

Para recuperar as definições de métrica usando a API REST do Azure Monitor, use "2016-03-01" como a versão da API.To retrieve metric definitions using the Azure Monitor REST API, use "2016-03-01" as the API version.

O corpo de resposta JSON resultante seria semelhante ao exemplo a seguir:The resulting JSON response body would be similar to the following example:

{
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Logic/workflows/ContosoTweets/providers/microsoft.insights/metricdefinitions",
  "value": [
    {
      "name": {
        "value": "RunsStarted",
        "localizedValue": "Runs Started"
      },
      "category": "AllMetrics",
      "startTime": "0001-01-01T00:00:00Z",
      "endTime": "0001-01-01T00:00:00Z",
      "unit": "Count",
      "primaryAggregationType": "Total",
      "resourceUri": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Logic/workflows/ContosoTweets",
      "resourceId": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Logic/workflows/ContosoTweets",
      "metricAvailabilities": [
        {
          "timeGrain": "PT1M",
          "retention": "P30D",
          "location": null,
          "blobLocation": null
        },
        {
          "timeGrain": "PT1H",
          "retention": "P30D",
          "location": null,
          "blobLocation": null
        }
      ],
      "properties": null,
      "dimensions": null,
      "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Logic/workflows/ContosoTweets/providers/microsoft.insights/metricdefinitions/RunsStarted",
      "supportedAggregationTypes": [ "None", "Average", "Minimum", "Maximum", "Total", "Count" ]
    }
  ]
}

Para obter mais informações, consulte a documentação Listar as definições de métricas para um recurso na API REST do Azure Monitor .For more information, see the List the metric definitions for a resource in Azure Monitor REST API documentation.

Recuperar valores de métricaRetrieve metric values

Depois que as definições de métrica disponíveis são conhecidas, é possível recuperar os valores de métrica relacionados.Once the available metric definitions are known, it is then possible to retrieve the related metric values. Use o nome da métrica ' value ' (não o ' localizador ') para quaisquer solicitações de filtragem (por exemplo, recupere os pontos de dados de métrica ' CpuTime ' e ' solicitações ').Use the metric’s name ‘value’ (not the ‘localizedValue’) for any filtering requests (for example, retrieve the ‘CpuTime’ and ‘Requests’ metric data points). Se nenhum filtro for especificado, a métrica padrão será retornada.If no filters are specified, the default metric is returned.

Observação

Para recuperar valores de métrica usando a API REST do Azure Monitor, use "2016-09-01" como a versão da API.To retrieve metric values using the Azure Monitor REST API, use "2016-09-01" as the API version.

Método: GETMethod: GET

URI da solicitação: https://management.azure.com/subscriptions/ {Subscription-ID} /resourceGroups/ {nome-do-grupo-de-recursos} /Providers/ {Resource-Provider-namespace} / {tipo de recurso} / {nome-do-recurso} /Providers/ Microsoft. insights/métricas? $filter = {filtro} & API-Version = {apiVersion}Request URI: https://management.azure.com/subscriptions/*{subscription-id}*/resourceGroups/*{resource-group-name}*/providers/*{resource-provider-namespace}*/*{resource-type}*/*{resource-name}*/providers/microsoft.insights/metrics?$filter=*{filter}*&api-version=*{apiVersion}*

Por exemplo, para recuperar os pontos de dados da métrica RunsSucceeded para o intervalo de tempo determinado e, por uma hora, de 1 hora, a solicitação seria a seguinte:For example, to retrieve the RunsSucceeded metric data points for the given time range and for a time grain of 1 hour, the request would be as follows:

$filter = "(name.value eq 'RunsSucceeded') and aggregationType eq 'Total' and startTime eq 2017-08-18T19:00:00 and endTime eq 2017-08-18T23:00:00 and timeGrain eq duration'PT1H'"
$request = "https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Logic/workflows/ContosoTweets/providers/microsoft.insights/metrics?`$filter=${filter}&api-version=2016-09-01"
Invoke-RestMethod -Uri $request `
    -Headers $authHeader `
    -Method Get `
    -OutFile ".\contosotweets-metrics-results.json" `
    -Verbose

O corpo de resposta JSON resultante seria semelhante ao exemplo a seguir:The resulting JSON response body would be similar to the following example:

{
  "value": [
    {
      "data": [
        {
          "timeStamp": "2017-08-18T19:00:00Z",
          "total": 0.0
        },
        {
          "timeStamp": "2017-08-18T20:00:00Z",
          "total": 159.0
        },
        {
          "timeStamp": "2017-08-18T21:00:00Z",
          "total": 174.0
        },
        {
          "timeStamp": "2017-08-18T22:00:00Z",
          "total": 97.0
        }
      ],
      "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Logic/workflows/ContosoTweets/providers/Microsoft.Insights/metrics/RunsSucceeded",
      "name": {
        "value": "RunsSucceeded",
        "localizedValue": "Runs Succeeded"
      },
      "type": "Microsoft.Insights/metrics",
      "unit": "Count"
    }
  ]
}

Para recuperar vários pontos de dados ou de agregação, adicione os nomes de definição de métrica e os tipos de agregação ao filtro, como mostrado no exemplo a seguir:To retrieve multiple data or aggregation points, add the metric definition names and aggregation types to the filter, as seen in the following example:

$filter = "(name.value eq 'ActionsCompleted' or name.value eq 'RunsSucceeded') and (aggregationType eq 'Total' or aggregationType eq 'Average') and startTime eq 2017-08-18T21:00:00 and endTime eq 2017-08-18T21:30:00 and timeGrain eq duration'PT1M'"
$request = "https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Logic/workflows/ContosoTweets/providers/microsoft.insights/metrics?`$filter=${filter}&api-version=2016-09-01"
Invoke-RestMethod -Uri $request `
    -Headers $authHeader `
    -Method Get `
    -OutFile ".\contosotweets-metrics-multiple-results.json" `
    -Verbose

O corpo de resposta JSON resultante seria semelhante ao exemplo a seguir:The resulting JSON response body would be similar to the following example:

{
  "value": [
    {
      "data": [
        {
          "timeStamp": "2017-08-18T21:03:00Z",
          "total": 5.0,
          "average": 1.0
        },
        {
          "timeStamp": "2017-08-18T21:04:00Z",
          "total": 7.0,
          "average": 1.0
        }
      ],
      "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Logic/workflows/ContosoTweets/providers/Microsoft.Insights/metrics/ActionsCompleted",
      "name": {
        "value": "ActionsCompleted",
        "localizedValue": "Actions Completed "
      },
      "type": "Microsoft.Insights/metrics",
      "unit": "Count"
    },
    {
      "data": [
        {
          "timeStamp": "2017-08-18T21:03:00Z",
          "total": 5.0,
          "average": 1.0
        },
        {
          "timeStamp": "2017-08-18T21:04:00Z",
          "total": 7.0,
          "average": 1.0
        }
      ],
      "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Logic/workflows/ContosoTweets/providers/Microsoft.Insights/metrics/RunsSucceeded",
      "name": {
        "value": "RunsSucceeded",
        "localizedValue": "Runs Succeeded"
      },
      "type": "Microsoft.Insights/metrics",
      "unit": "Count"
    }
  ]
}

Usar ARMClientUse ARMClient

Uma abordagem adicional é usar o ARMClient em seu computador Windows.An additional approach is to use ARMClient on your Windows machine. ARMClient manipula a autenticação do Azure AD (e o token JWT resultante) automaticamente.ARMClient handles the Azure AD authentication (and resulting JWT token) automatically. As etapas a seguir descrevem o uso de ARMClient para recuperar dados de métrica:The following steps outline the use of ARMClient for retrieving metric data:

  1. Instalar Chocolatey e ARMClient.Install Chocolatey and ARMClient.
  2. Em uma janela de terminal, digite armclient.exe login.In a terminal window, type armclient.exe login. Isso solicitará que você faça logon no Azure.Doing so prompts you to log in to Azure.
  3. Digite armclient GET [your_resource_id]/providers/microsoft.insights/metricdefinitions?api-version=2016-03-01Type armclient GET [your_resource_id]/providers/microsoft.insights/metricdefinitions?api-version=2016-03-01
  4. Digite ARMCLIENT Get [your_resource_id]/Providers/Microsoft.insights/Metrics? API-Version = 2016-09-01Type armclient GET [your_resource_id]/providers/microsoft.insights/metrics?api-version=2016-09-01

Por exemplo, para recuperar as definições de métrica para um aplicativo lógico específico, emita o seguinte comando:For example, in order to retrieve the metric definitions for a specific Logic App, issue the following command:

armclient GET /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Logic/workflows/ContosoTweets/providers/microsoft.insights/metricDefinitions?api-version=2016-03-01

Recuperar a ID do recursoRetrieve the resource ID

Usar a API REST pode realmente ajudar a entender as definições de métrica disponíveis, a granularidade e os valores relacionados.Using the REST API can really help to understand the available metric definitions, granularity, and related values. Essas informações são úteis ao usar a Biblioteca de Gerenciamento do Azure.That information is helpful when using the Azure Management Library.

Para o código anterior, a ID de recurso a ser usada é o caminho completo para o recurso do Azure desejado.For the preceding code, the resource ID to use is the full path to the desired Azure resource. Por exemplo, para consultar um aplicativo Web do Azure, a ID do recurso seria:For example, to query against an Azure Web App, the resource ID would be:

/subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.Web/sites/{site-name}//subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.Web/sites/{site-name}/

A lista a seguir contém alguns exemplos de formatos de ID do recurso para vários recursos do Azure:The following list contains a few examples of resource ID formats for various Azure resources:

  • Hub IoT - /subscriptions/ {id-da-assinatura} /resourceGroups/ {nome-do-grupo-de-recursos} /providers/Microsoft.Devices/IotHubs/ {nome-do-hub-iot}IoT Hub - /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.Devices/IotHubs/{iot-hub-name}
  • Pool SQL Elástico - /subscriptions/ {subscription-id} /resourceGroups/ {resource-group-name} /providers/Microsoft.Sql/servers/ {pool-db} /elasticpools/ {sql-pool-name}Elastic SQL Pool - /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.Sql/servers/{pool-db}/elasticpools/{sql-pool-name}
  • Banco de Dados SQL (v12) - /subscriptions/ {id-da-assinatura} /resourceGroups/ {nome-do-grupo-de-recursos} /providers/Microsoft.Sql/servers/ {nome-do-servidor} /databases/ {nome-do-banco-de-dados}SQL Database (v12) - /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.Sql/servers/{server-name}/databases/{database-name}
  • Barramento de Serviço - /subscriptions/ {id-da-assinatura} /resourceGroups/ {nome-do-grupo-de-recursos} /providers/Microsoft.ServiceBus/ {namespace} / {servicebus-name}Service Bus - /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.ServiceBus/{namespace}/{servicebus-name}
  • Conjuntos de dimensionamento de máquinas virtuais -/subscriptions/ {Subscription-ID} /resourceGroups/ {Resource-Group-Name} /Providers/Microsoft.Compute/virtualMachineScaleSets/ {VM-Name}Virtual machine scale sets - /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachineScaleSets/{vm-name}
  • VMs - /subscriptions/ {id-da-assinatura} /resourceGroups/ {nome-do-grupo-de-recursos} /providers/Microsoft.Compute/virtualMachines/ {vm-name}VMs - /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.Compute/virtualMachines/{vm-name}
  • Hubs de Eventos - /subscriptions/ {id-da-assinatura} /resourceGroups/ {nome-do-grupo-de-recursos} /providers/Microsoft.EventHub/namespaces/ {eventhub-namespace}Event Hubs - /subscriptions/{subscription-id}/resourceGroups/{resource-group-name}/providers/Microsoft.EventHub/namespaces/{eventhub-namespace}

Há abordagens alternativas para recuperar a ID do recurso, incluindo o uso de Azure Resource Explorer, a exibição do recurso desejado no portal do Azure e o PowerShell ou o CLI do Azure.There are alternative approaches to retrieving the resource ID, including using Azure Resource Explorer, viewing the desired resource in the Azure portal, and via PowerShell or the Azure CLI.

Azure Resource ManagerAzure Resource Explorer

Para localizar a ID do recurso para um recurso desejado, uma abordagem útil é usar a ferramenta Azure Resource Manager .To find the resource ID for a desired resource, one helpful approach is to use the Azure Resource Explorer tool. Navegue até o recurso desejado e examine a ID mostrada, como na seguinte captura de tela:Navigate to the desired resource and then look at the ID shown, as in the following screenshot:

Alt "Azure Resource Explorer"

Portal do AzureAzure portal

A ID do recurso também pode ser obtida no portal do Azure.The resource ID can also be obtained from the Azure portal. Para fazer isso, navegue até o recurso desejado e, em seguida, selecione Propriedades.To do so, navigate to the desired resource and then select Properties. A ID do recurso é exibida na seção Propriedades, como mostrado na seguinte captura de tela:The Resource ID is displayed in the Properties section, as seen in the following screenshot:

Alt "ID do recurso exibida na folha de propriedades no portal do Azure"

Azure PowerShellAzure PowerShell

A ID do recurso também pode ser recuperada usando cmdlets Azure PowerShell.The resource ID can be retrieved using Azure PowerShell cmdlets as well. Por exemplo, para obter a ID de recurso para um aplicativo lógico do Azure, execute o cmdlet Get-AzureLogicApp, como no exemplo a seguir:For example, to obtain the resource ID for an Azure Logic App, execute the Get-AzureLogicApp cmdlet, as in the following example:

Get-AzLogicApp -ResourceGroupName azmon-rest-api-walkthrough -Name contosotweets

O resultado deve ser semelhante ao exemplo a seguir:The result should be similar to the following example:

Id             : /subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Logic/workflows/ContosoTweets
Name           : ContosoTweets
Type           : Microsoft.Logic/workflows
Location       : centralus
ChangedTime    : 8/21/2017 6:58:57 PM
CreatedTime    : 8/18/2017 7:54:21 PM
AccessEndpoint : https://prod-08.centralus.logic.azure.com:443/workflows/f3a91b352fcc47e6bff989b85446c5db
State          : Enabled
Definition     : {$schema, contentVersion, parameters, triggers...}
Parameters     : {[$connections, Microsoft.Azure.Management.Logic.Models.WorkflowParameter]}
SkuName        :
AppServicePlan :
PlanType       :
PlanId         :
Version        : 08586982649483762729

Azure CLIAzure CLI

Para recuperar a ID de recurso para uma conta de armazenamento do Azure usando o CLI do Azure, execute o comando az storage account show, conforme mostrado no exemplo a seguir:To retrieve the resource ID for an Azure Storage account using the Azure CLI, execute the az storage account show command, as shown in the following example:

az storage account show -g azmon-rest-api-walkthrough -n contosotweets2017

O resultado deve ser semelhante ao exemplo a seguir:The result should be similar to the following example:

{
  "accessTier": null,
  "creationTime": "2017-08-18T19:58:41.840552+00:00",
  "customDomain": null,
  "enableHttpsTrafficOnly": false,
  "encryption": null,
  "id": "/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/resourceGroups/azmon-rest-api-walkthrough/providers/Microsoft.Storage/storageAccounts/contosotweets2017",
  "identity": null,
  "kind": "Storage",
  "lastGeoFailoverTime": null,
  "location": "centralus",
  "name": "contosotweets2017",
  "networkAcls": null,
  "primaryEndpoints": {
    "blob": "https://contosotweets2017.blob.core.windows.net/",
    "file": "https://contosotweets2017.file.core.windows.net/",
    "queue": "https://contosotweets2017.queue.core.windows.net/",
    "table": "https://contosotweets2017.table.core.windows.net/"
  },
  "primaryLocation": "centralus",
  "provisioningState": "Succeeded",
  "resourceGroup": "azmon-rest-api-walkthrough",
  "secondaryEndpoints": null,
  "secondaryLocation": "eastus2",
  "sku": {
    "name": "Standard_GRS",
    "tier": "Standard"
  },
  "statusOfPrimary": "available",
  "statusOfSecondary": "available",
  "tags": {},
  "type": "Microsoft.Storage/storageAccounts"
}

Observação

Os aplicativos lógicos do Azure ainda não estão disponíveis por meio do CLI do Azure, portanto, uma conta de armazenamento do Azure é mostrada no exemplo anterior.Azure Logic Apps are not yet available via the Azure CLI, thus an Azure Storage account is shown in the preceding example.

Recuperar dados do log de atividadesRetrieve activity log data

Além das definições de métrica e valores relacionados, também é possível usar a API REST Azure Monitor para recuperar informações interessantes adicionais relacionadas aos recursos do Azure.In addition to metric definitions and related values, it is also possible to use the Azure Monitor REST API to retrieve additional interesting insights related to Azure resources. Por exemplo, é possível consultar os dados do log de atividades .As an example, it is possible to query activity log data. O exemplo a seguir demonstra como usar a API REST Azure Monitor para consultar dados do log de atividades em um intervalo de datas específico para uma assinatura do Azure:The following sample demonstrates using the Azure Monitor REST API to query activity log data within a specific date range for an Azure subscription:

$apiVersion = "2015-04-01"
$filter = "eventTimestamp ge '2017-08-18' and eventTimestamp le '2017-08-19'and eventChannels eq 'Admin, Operation'"
$request = "https://management.azure.com/subscriptions/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/providers/microsoft.insights/eventtypes/management/values?api-version=${apiVersion}&`$filter=${filter}"
Invoke-RestMethod -Uri $request `
    -Headers $authHeader `
    -Method Get `
    -Verbose

Próximos passosNext steps