Compartir vía

Acceso a la API de Azure Monitor Log Analytics

Puede enviar una solicitud de consulta a un área de trabajo mediante el punto de conexión de Azure Monitor Log Analytics https://api.loganalytics.azure.com. Para acceder al punto de conexión, debe autenticarse a través de Microsoft Entra ID.

Nota:

El api.loganalytics.io punto de conexión se va a reemplazar por api.loganalytics.azure.com. El punto de conexión de api.loganalytics.io seguirá siendo compatible con el futuro previsible.

Autenticación con una clave de API de demostración

Para explorar rápidamente la API sin Microsoft Entra autenticación, use el área de trabajo de demostración con datos de ejemplo, que admite la autenticación de clave de API.

Para autenticar y ejecutar consultas en el área de trabajo de ejemplo, use DEMO_WORKSPACE como {workspace-id} y pase la clave de API DEMO_KEY.

Si el Id. de aplicación o la clave de API son incorrectos, el servicio de API devolverá un error 403 (prohibido).

La clave de API DEMO_KEY se puede pasar de tres maneras diferentes, dependiendo de si quiere usar un encabezado, la dirección URL o la autenticación básica:

  • Encabezado personalizado: Proporcione la clave de API en el encabezado X-Api-Key personalizado.
  • Parámetro de consulta: Proporcione la clave de API en el parámetro de dirección URL api_key.
  • Autenticación básica: Proporcione la clave de API como nombre de usuario o contraseña. Si proporciona ambos, la clave de API debe estar en el nombre de usuario.

En este ejemplo se usa el Id. del área de trabajo y la clave de API en el encabezado:

POST https://api.loganalytics.azure.com/v1/workspaces/DEMO_WORKSPACE/query
X-Api-Key: DEMO_KEY
Content-Type: application/json

{
    "query": "AzureActivity | summarize count() by Category"
}

Punto de conexión de API pública

El punto de conexión de API pública es:

https://api.loganalytics.azure.com/{api-version}/workspaces/{workspaceId}

Donde:

  • api-version: la versión API. La versión actual es v1.
  • workspaceId: Id. del área de trabajo.

Nota:

La beta versión de api está en desuso. Para obtener más información, consulte Migración desde el uso de API de consulta por lotes y beta.

La consulta se pasa en el cuerpo de la solicitud.

Por ejemplo:

https://api.loganalytics.azure.com/v1/workspaces/a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1

Body:
{
    "query": "Usage"
}

Configuración de la autenticación

Para acceder a la API, registre una aplicación cliente con Microsoft Entra ID y solicite un token.

  1. Registrar una aplicación en Microsoft Entra ID.

  2. En la página de información general de la aplicación, seleccione Permisos de API.

  3. Seleccione Agregar un permiso.

  4. En la pestaña APIs que usa mi organización, busque Log Analytics y seleccione Log Analytics API en la lista.

    Captura de pantalla que muestra la página Solicitar permisos de API.

  5. Seleccione Permisos delegados.

  6. Seleccione la casilla Data.Read.

  7. Seleccione Agregar permisos.

    Captura de pantalla que muestra la continuación de la página Solicitar permisos de API.

Ahora que la aplicación está registrada y tiene permisos para usar la API, conceda a la aplicación acceso al área de trabajo de Log Analytics.

  1. En la página de información general del área de trabajo de Log Analytics, seleccione Acceso controlado (IAM).

  2. Seleccione Agregar asignación de roles.

    Una captura de pantalla que muestra la página de Control de acceso de un área de trabajo de Log Analytics.

  3. Seleccione el rol Lector y, a continuación, seleccione Miembros.

    Captura de pantalla que muestra la página Agregar asignación de roles para un área de trabajo de Log Analytics.

  4. En la pestaña Miembros, elija Seleccionar miembros.

  5. Escriba el nombre de la aplicación en el cuadro Seleccionar.

  6. Seleccione la aplicación y elija Seleccionar.

  7. Seleccione Revisar y asignar.

    Una captura de pantalla que muestra el panel Seleccionar miembros en la página Agregar asignación de roles de un área de trabajo de Log Analytics.

  8. Después de finalizar la configuración de Active Directory y los permisos del área de trabajo, solicite un token de autorización.

Nota:

En este ejemplo, hemos aplicado el rol de lector. Este rol es uno de los muchos roles integrados y puede incluir más permisos de los que necesita. Se pueden crear roles y permisos más granulares. Para obtener más información, consulte Administrar el acceso a Log Analytics áreas de trabajo.

Solicitud de un token de autorización

Antes de comenzar, asegúrese de que tiene todos los valores necesarios para realizar la solicitud correctamente. Todas las solicitudes requieren:

  • Identificador de inquilino de Microsoft Entra.
  • ID del área de trabajo.
  • El identificador de cliente de Microsoft Entra para la aplicación.
  • El secreto de cliente de Microsoft Entra para la aplicación.

La API de Log Analytics admite la autenticación Microsoft Entra con tres flujos de Microsoft Entra ID OAuth2 diferentes:

  • Credenciales de cliente
  • Código de autorización
  • Implícito

Flujo de credenciales de cliente

En el flujo de credenciales de cliente, el token se usa con el punto de conexión de Log Analytics. Se realiza una única solicitud para recibir un token mediante las credenciales proporcionadas para la aplicación en el paso anterior al registrar una aplicación en Microsoft Entra ID.

Utilice resource=https://api.loganalytics.azure.com.

Obtenga un token de autenticación mediante cualquiera de los siguientes métodos:

  • Interfaz de línea de comandos (CLI)
  • REST API
  • SDK

Obtención de un token mediante una solicitud de REST

Use la siguiente llamada a la API de REST para obtener un token. Esta solicitud usa un identificador de cliente y un secreto de cliente para autenticar la solicitud. El identificador de cliente y el secreto de cliente se obtienen al registrar la aplicación con Microsoft Entra ID. Para obtener más información, consulte Registro de una aplicación para solicitar tokens de autorización y trabajar con API.

curl -X POST 'https://login.microsoftonline.com/<tennant ID>/oauth2/token' \
-H 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=client_credentials' \
--data-urlencode 'client_id=<your apps client ID>' \
--data-urlencode 'client_secret=<your apps client secret' \
--data-urlencode 'resource={resource URI of the service you want to access, e.g. https://monitoring.azure.com>'}'

El cuerpo de la respuesta aparece en el formato siguiente:

{
    "token_type": "Bearer",
    "expires_in": "86399",
    "ext_expires_in": "86399",
    "expires_on": "1672826207",
    "not_before": "1672739507",
    "resource": "{resource URI of the service you want to access, e.g. https://monitoring.azure.com>'}",
    "access_token": "eyJ0eXAiOiJKV1Qi....gpHWoRzeDdVQd2OE3dNsLIvUIxQ"
}

Use el token en las solicitudes al punto de conexión de Log Analytics:

POST /v1/workspaces/your workspace id/query?timespan=P1D
Host: https://api.loganalytics.azure.com
Content-Type: application/json
Authorization: Bearer <your access token>

Body:

{
"query": "AzureActivity |summarize count() by Category"
}

Respuesta de ejemplo:

{
    "tables": [
        {
            "name": "PrimaryResult",
            "columns": [
                {
                    "name": "OperationName",
                    "type": "string"
                },
                {
                    "name": "Level",
                    "type": "string"
                },
                {
                    "name": "ActivityStatus",
                    "type": "string"
                }
            ],
            "rows": [
                [
                    "Metric Alert",
                    "Informational",
                    "Resolved",
                    ...
                ],
                ...
            ]
        },
        ...
    ]
}

Flujo del código de autorización

El flujo principal de OAuth2 admitido es a través de códigos de autorización. Este método requiere dos solicitudes HTTP para adquirir un token con el que llamar a la API de Azure Monitor Log Analytics. Hay dos direcciones URL, con un punto de conexión por solicitud. Los formatos se describen en las secciones siguientes.

Dirección URL del código de autorización (solicitud GET)

GET https://login.microsoftonline.com/YOUR_Azure AD_TENANT/oauth2/authorize?
client_id=<app-client-id>
&response_type=code
&redirect_uri=<app-redirect-uri>
&resource=https://api.loganalytics.io

Cuando se realiza una solicitud a la dirección URL de autorización, el client_id es el identificador de aplicación de la aplicación de Microsoft Entra, copiado en el menú de propiedades de la aplicación. El redirect_uri es la dirección URL de inicio o inicio de sesión de la misma aplicación Microsoft Entra. Cuando una solicitud se realiza correctamente, este punto de conexión le redirige a la página de inicio de sesión que proporcionó en el registro con el código de autorización anexado a la dirección URL. Observe el ejemplo siguiente:

http://<app-client-id>/?code=AUTHORIZATION_CODE&session_state=STATE_GUID

En este punto, has obtenido un código de autorización, que ahora necesitas para solicitar un token de acceso.

Dirección URL del token de código de autorización (solicitud POST)

POST /YOUR_Azure AD_TENANT/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=<app client id>
&code=<auth code fom GET request>
&redirect_uri=<app-client-id>
&resource=https://api.loganalytics.io
&client_secret=<app-client-secret>

Todos los valores son los mismos que antes, con algunas adiciones. El código de autorización es el mismo código que recibió en la solicitud anterior después de un redireccionamiento correcto. El código se combina con la clave obtenida de la aplicación Microsoft Entra. Si no guardó la clave, puede eliminarla y crear una nueva desde la pestaña claves del menú Microsoft Entra aplicación. La respuesta es una cadena JSON que contiene el token con el esquema siguiente. Los tipos se indican para los valores del token.

Respuesta de ejemplo:

{
    "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
    "expires_in": "3600",
    "ext_expires_in": "1503641912",
    "id_token": "not_needed_for_log_analytics",
    "not_before": "1503638012",
    "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az",
    "resource": "https://api.loganalytics.io",
    "scope": "Data.Read",
    "token_type": "bearer"
}

La parte del token de acceso de esta respuesta es la que se presenta a la API de Log Analytics en el encabezado Authorization: Bearer. También puede usar el token de actualización en el futuro para adquirir un nuevo access_token y refresh_token cuando el suyo haya quedado obsoleto. Para esta solicitud, el formato y el punto de conexión son:

POST /YOUR_AAD_TENANT/oauth2/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=<app-client-id>
&refresh_token=<refresh-token>
&grant_type=refresh_token
&resource=https://api.loganalytics.io
&client_secret=<app-client-secret>

Respuesta de ejemplo:

{
    "token_type": "Bearer",
    "expires_in": "3600",
    "expires_on": "1460404526",
    "resource": "https://api.loganalytics.io",
    "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
    "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az"
}

Flujo de credenciales de cliente

La API de Log Analytics admite el flujo de credenciales del cliente OAuth2. Este flujo es adecuado para las llamadas de servicio a servicio en las que no se requiere ninguna interacción del usuario.

Solicitud de token de credenciales de cliente

POST https://login.microsoftonline.com/YOUR_AAD_TENANT/oauth2/v2.0/token HTTP/1.1
Host: login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id=<app-client-id>
&scope=https://api.loganalytics.io/.default
&client_secret=<app-client-secret>
&grant_type=client_credentials

Respuesta de ejemplo:

{
    "token_type": "Bearer",
    "expires_in": 3599,
    "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax"
}

Este access_token se puede usar como valor de encabezado Authorization: Bearer cuando se pasa a la API de Log Analytics para autorizar solicitudes.

Más información

Puede encontrar documentación sobre OAuth2 con Microsoft Entra aquí:

Pasos siguientes

  • Last updated on