Listar logons

Artigo
03/18/2024

Namespace: microsoft.graph

Recupere as Microsoft Entra entradas do usuário para seu locatário. Entradas interativas por natureza (em que um nome de usuário/senha é passado como parte do token de auth) e entradas federadas bem-sucedidas estão atualmente incluídas nos logs de entrada.

O tamanho máximo e padrão da página é de 1.000 objetos e, por padrão, as entradas mais recentes são retornadas primeiro. Somente os eventos de entrada que ocorreram no período de retenção padrão Microsoft Entra ID estão disponíveis.

Observação

Este artigo descreve como exportar dados pessoais de um dispositivo ou serviço. Essas etapas podem ser usadas para dar suporte às suas obrigações de acordo com o GDPR (Regulamento Geral de Proteção de Dados). Os administradores de locatários autorizados podem usar o Microsoft Graph para corrigir, atualizar ou excluir informações identificáveis sobre usuários finais, incluindo perfis de usuário de clientes e funcionários ou dados pessoais, como nome do usuário, título de trabalho, endereço ou número de telefone, em seu ambiente Microsoft Entra ID.

Essa API está disponível nas seguintes implantações nacionais de nuvem.

Serviço global	Governo dos EUA L4	GOVERNO DOS EUA L5 (DOD)	China operada pela 21Vianet
✅	❌	❌	❌

Permissões

Uma das seguintes permissões é necessária para chamar esta API. Para saber mais, incluindo como escolher permissões, confira Permissões.

Tipo de permissão	Permissões (da com menos para a com mais privilégios)
Delegado (conta corporativa ou de estudante)	AuditLog.Read.All e Directory.Read.All
Delegado (conta pessoal da Microsoft)	Sem suporte
Aplicativo	AuditLog.Read.All e Directory.Read.All

Os aplicativos devem ser registrados corretamente para Microsoft Entra ID.

Além das permissões delegadas, o usuário conectado precisa pertencer a pelo menos uma das seguintes Microsoft Entra funções:

Leitor Global
Leitor de Relatórios
Administrador de Segurança
Operador de Segurança
Leitor de Segurança

Exibir políticas de AC (acesso condicional) aplicadas em entradas

As políticas de AC aplicadas listadas na propriedade appliedConditionalAccessPolicies só estão disponíveis para usuários e aplicativos com funções que permitem ler dados de acesso condicional. Se um usuário ou aplicativo tiver permissões para ler logs de entrada, mas não permissão para ler dados de acesso condicional, a propriedade appliedConditionalAccessPolicies na resposta será omitida. As seguintes funções de Microsoft Entra concedem aos usuários permissões para exibir dados de acesso condicional:

Leitor Global
Administrador de Segurança
Leitor de Segurança
Administrador de Acesso Condicional

Os aplicativos devem ter pelo menos uma das seguintes permissões para ver objetos appliedConditionalAccessPolicy nos logs de entrada:

Policy.Read.All
Policy.ReadWrite.ConditionalAccess
Policy.Read.ConditionalAccess

Solicitação HTTP

GET /auditLogs/signIns

Parâmetros de consulta opcionais

Esse método dá suporte aos $topparâmetros de consulta , $skiptokene $filter OData para ajudar a personalizar a resposta. Para obter informações gerais, acesse Parâmetros de consulta OData.

Para evitar ter o tempo limite de solicitação, aplique o $filter parâmetro com um intervalo de tempo para o qual obter todas as entradas, conforme mostrado no Exemplo 1.

Cabeçalhos de solicitação

Nome	Descrição
Autorização	{token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.

Resposta

Se bem-sucedido, esse método retornará um código de resposta 200 OK e uma coleção de objetos de logon no corpo da resposta. A coleção de objetos é listada em ordem decrescente com base em createdDateTime.

Exemplos

Exemplo 1: listar todas as entradas durante um período de tempo específico

Solicitação

O exemplo a seguir mostra uma solicitação para listar todas as entradas durante um período específico.

GET https://graph.microsoft.com/v1.0/auditLogs/signIns?$filter=createdDateTime ge 2024-07-01T00:00:00Z and createdDateTime le 2024-07-14T23:59:59Z


// Code snippets are only available for the latest version. Current version is 5.x

// To initialize your graphClient, see https://learn.microsoft.com/en-us/graph/sdks/create-client?from=snippets&tabs=csharp
var result = await graphClient.AuditLogs.SignIns.GetAsync((requestConfiguration) =>
{
	requestConfiguration.QueryParameters.Filter = "createdDateTime ge 2024-07-01T00:00:00Z and createdDateTime le 2024-07-14T23:59:59Z";
});


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc audit-logs sign-ins list --filter "createdDateTime ge 2024-07-01T00:00:00Z and createdDateTime le 2024-07-14T23:59:59Z"



import (
	  "context"
	  msgraphsdk "github.com/microsoftgraph/msgraph-sdk-go"
	  graphauditlogs "github.com/microsoftgraph/msgraph-sdk-go/auditlogs"
	  //other-imports
)

graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)



requestFilter := "createdDateTime ge 2024-07-01T00:00:00Z and createdDateTime le 2024-07-14T23:59:59Z"

requestParameters := &graphauditlogs.AuditLogsSignInsRequestBuilderGetQueryParameters{
	Filter: &requestFilter,
}
configuration := &graphauditlogs.AuditLogsSignInsRequestBuilderGetRequestConfiguration{
	QueryParameters: requestParameters,
}

signIns, err := graphClient.AuditLogs().SignIns().Get(context.Background(), configuration)


// Code snippets are only available for the latest version. Current version is 6.x

GraphServiceClient graphClient = new GraphServiceClient(requestAdapter);

SignInCollectionResponse result = graphClient.auditLogs().signIns().get(requestConfiguration -> {
	requestConfiguration.queryParameters.filter = "createdDateTime ge 2024-07-01T00:00:00Z and createdDateTime le 2024-07-14T23:59:59Z";
});


const options = {
	authProvider,
};

const client = Client.init(options);

let signIns = await client.api('/auditLogs/signIns')
	.filter('createdDateTime ge 2024-07-01T00:00:00Z and createdDateTime le 2024-07-14T23:59:59Z')
	.get();


<?php
use Microsoft\Graph\GraphServiceClient;
use Microsoft\Graph\Generated\AuditLogs\SignIns\SignInsRequestBuilderGetRequestConfiguration;


$graphServiceClient = new GraphServiceClient($tokenRequestContext, $scopes);

$requestConfiguration = new SignInsRequestBuilderGetRequestConfiguration();
$queryParameters = SignInsRequestBuilderGetRequestConfiguration::createQueryParameters();
$queryParameters->filter = "createdDateTime ge 2024-07-01T00:00:00Z and createdDateTime le 2024-07-14T23:59:59Z";
$requestConfiguration->queryParameters = $queryParameters;


$result = $graphServiceClient->auditLogs()->signIns()->get($requestConfiguration)->wait();


Import-Module Microsoft.Graph.Reports

Get-MgAuditLogSignIn -Filter "createdDateTime ge 2024-07-01T00:00:00Z and createdDateTime le 2024-07-14T23:59:59Z"


from msgraph import GraphServiceClient
from msgraph.generated.audit_logs.sign_ins.sign_ins_request_builder import SignInsRequestBuilder

graph_client = GraphServiceClient(credentials, scopes)

query_params = SignInsRequestBuilder.SignInsRequestBuilderGetQueryParameters(
		filter = "createdDateTime ge 2024-07-01T00:00:00Z and createdDateTime le 2024-07-14T23:59:59Z",
)

request_configuration = SignInsRequestBuilder.SignInsRequestBuilderGetRequestConfiguration(
query_parameters = query_params,
)

result = await graph_client.audit_logs.sign_ins.get(request_configuration = request_configuration)

Resposta

O exemplo a seguir mostra a resposta.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#auditLogs/signIns",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/auditLogs/signIns?$top=1&$skiptoken=9177f2e3532fcd4c4d225f68f7b9bdf7_1",
    "value": [
        {
            "id": "66ea54eb-6301-4ee5-be62-ff5a759b0100",
            "createdDateTime": "2023-12-01T16:03:35Z",
            "userDisplayName": "Test Contoso",
            "userPrincipalName": "testaccount1@contoso.com",
            "userId": "26be570a-ae82-4189-b4e2-a37c6808512d",
            "appId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
            "appDisplayName": "Graph explorer",
            "ipAddress": "131.107.159.37",
            "clientAppUsed": "Browser",
            "correlationId": "d79f5bee-5860-4832-928f-3133e22ae912",
            "conditionalAccessStatus": "notApplied",
            "isInteractive": true,
            "riskDetail": "none",
            "riskLevelAggregated": "none",
            "riskLevelDuringSignIn": "none",
            "riskState": "none",
            "riskEventTypes": [],
            "resourceDisplayName": "Microsoft Graph",
            "resourceId": "00000003-0000-0000-c000-000000000000",
            "status": {
                "errorCode": 0,
                "failureReason": null,
                "additionalDetails": null
            },
            "deviceDetail": {
                "deviceId": "",
                "displayName": null,
                "operatingSystem": "Windows 10",
                "browser": "Edge 80.0.361",
                "isCompliant": null,
                "isManaged": null,
                "trustType": null
            },
            "location": {
                "city": "Redmond",
                "state": "Washington",
                "countryOrRegion": "US",
                "geoCoordinates": {
                    "altitude": null,
                    "latitude": 47.68050003051758,
                    "longitude": -122.12094116210938
                }
            },
            "appliedConditionalAccessPolicies": [
                {
                    "id": "de7e60eb-ed89-4d73-8205-2227def6b7c9",
                    "displayName": "SharePoint limited access for guest workers",
                    "enforcedGrantControls": [],
                    "enforcedSessionControls": [],
                    "result": "notEnabled"
                },
                {
                    "id": "6701123a-b4c6-48af-8565-565c8bf7cabc",
                    "displayName": "Medium signin risk block",
                    "enforcedGrantControls": [],
                    "enforcedSessionControls": [],
                    "result": "notEnabled"
                },
              ]
        }
    ]
}

Exemplo 2: recuperar as primeiras 10 entradas em aplicativos com o appDisplayName que começa com 'Graph'

Solicitação

O exemplo a seguir mostra uma solicitação.

GET https://graph.microsoft.com/v1.0/auditLogs/signIns?&$filter=startsWith(appDisplayName,'Graph')&$top=10

Snippet not available


// THE CLI IS IN PREVIEW. NON-PRODUCTION USE ONLY
mgc audit-logs sign-ins list --top "10" --filter "startsWith(appDisplayName,'Graph')"

Snippet not available

Snippet not available


const options = {
	authProvider,
};

const client = Client.init(options);

let signIns = await client.api('/auditLogs/signIns')
	.filter('startsWith(appDisplayName,\'Graph\')')
	.top(10)
	.get();

Snippet not available


Import-Module Microsoft.Graph.Reports

Get-MgAuditLogSignIn -Filter "startsWith(appDisplayName,'Graph')" -Top 10

Snippet not available

Resposta

O exemplo a seguir mostra a resposta. A resposta inclui uma @odata.nextLink propriedade que contém uma URL que pode ser usada para recuperar os próximos 10 resultados.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#auditLogs/signIns",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/auditLogs/signins?$filter=startsWith(appDisplayName%2c%27Graph%27)&$top=10&$skiptoken=70f66c0893886b49370ffdb44cd8d137b1a12b9ba02f34a16f33c5e0f7c42fc7",
    "value": [
        {
            "id": "66ea54eb-6301-4ee5-be62-ff5a759b0100",
            "createdDateTime": "2023-12-01T16:03:32Z",
            "userDisplayName": "Test Contoso",
            "userPrincipalName": "testaccount1@contoso.com",
            "userId": "26be570a-ae82-4189-b4e2-a37c6808512d",
            "appId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
            "appDisplayName": "Graph explorer",
            "ipAddress": "131.107.159.37",
            "clientAppUsed": "Browser",
            "correlationId": "d79f5bee-5860-4832-928f-3133e22ae912",
            "conditionalAccessStatus": "notApplied",
            "isInteractive": true,
            "riskDetail": "none",
            "riskLevelAggregated": "none",
            "riskLevelDuringSignIn": "none",
            "riskState": "none",
            "riskEventTypes": [],
            "resourceDisplayName": "Microsoft Graph",
            "resourceId": "00000003-0000-0000-c000-000000000000",
            "status": {
                "errorCode": 0,
                "failureReason": null,
                "additionalDetails": null
            },
            "deviceDetail": {
                "deviceId": "",
                "displayName": null,
                "operatingSystem": "Windows 10",
                "browser": "Edge 80.0.361",
                "isCompliant": null,
                "isManaged": null,
                "trustType": null
            },
            "location": {
                "city": "Redmond",
                "state": "Washington",
                "countryOrRegion": "US",
                "geoCoordinates": {
                    "altitude": null,
                    "latitude": 47.68050003051758,
                    "longitude": -122.12094116210938
                }
            },
            "appliedConditionalAccessPolicies": [
                {
                    "id": "de7e60eb-ed89-4d73-8205-2227def6b7c9",
                    "displayName": "SharePoint limited access for guest workers",
                    "enforcedGrantControls": [],
                    "enforcedSessionControls": [],
                    "result": "notEnabled"
                },
                {
                    "id": "6701123a-b4c6-48af-8565-565c8bf7cabc",
                    "displayName": "Medium signin risk block",
                    "enforcedGrantControls": [],
                    "enforcedSessionControls": [],
                    "result": "notEnabled"
                },
              ]
        }
    ]
}

Listar logons

Permissões

Exibir políticas de AC (acesso condicional) aplicadas em entradas

Solicitação HTTP

Parâmetros de consulta opcionais

Cabeçalhos de solicitação

Resposta

Exemplos

Exemplo 1: listar todas as entradas durante um período de tempo específico

Solicitação

Resposta

Exemplo 2: recuperar as primeiras 10 entradas em aplicativos com o appDisplayName que começa com 'Graph'

Solicitação

Resposta

Comentários

Comentários

Recursos adicionais