Imposta raccolta log API REST

Oracle Log Analytics fornisce già l'origine log definita da Oracle per la raccolta dei log dell'API REST. Verificare se è possibile utilizzare l'origine API REST definita da Oracle disponibile o qualsiasi parser definito da Oracle. In caso contrario, effettuare le operazioni riportate di seguito per creare una nuova origine log.

Prima di iniziare, se è necessario creare un nuovo parser adatto ai log, completarlo. Vedere Creare un parser.

1. Aprire il menu di navigazione e fare clic su Observability & Management. In Log Analytics, fare clic su Amministrazione.

   Le risorse di amministrazione sono elencate nel riquadro di navigazione a sinistra in Amministrazione. Fare clic su Origini.

2. Viene visualizzata la pagina Origini. Fare clic su Crea origine.

   Viene visualizzata la finestra di dialogo Crea origine.

3. Nel campo Nome, immettere il nome dell'origine log.

4. Nell'elenco Tipo di origine selezionare API REST.

5. Fare clic su Tipo di entità e selezionare il tipo che meglio identifica l'applicazione.

6. Fare clic su Parser e selezionare un parser adatto per il tipo di log che si desidera raccogliere.

7. Nella scheda Endpoint fare clic su Aggiungi endpoint di log o su Aggiungi endpoint di lista per più log a seconda delle esigenze.

   • Per fornire un singolo URL endpoint di log che consente di raccogliere i log in modo continuo, fare clic su Aggiungi endpoint di log. Viene visualizzata la finestra di dialogo Aggiungi endpoint di log.

     Fornire le informazioni riportate di seguito.

     1. Immettere il nome endpoint di log.

     2. Creare l'URL di log per raccogliere periodicamente i log. Vedere URL endpoint di log in Tipi di URL endpoint.

     3. Selezionare il metodo API GET o POST.

        Se è stato selezionato POST, immettere il payload POST per il metodo e selezionare il tipo di contenuto della richiesta da JSON, Text, Javascript, HTML e XML.

     4. Facoltativamente, specificare l'URL del server proxy di log.

     5. Facoltativamente, fare clic su Mostra intestazioni richiesta per espandere la sezione e fare clic su Aggiungi per fornire le intestazioni delle richieste sotto forma di coppie Nome-Valore.

     6. Facoltativamente, fare clic su Mostra parametri di query per espandere la sezione e fare clic su Aggiungi per fornire eventuali parametri di query sotto forma di coppie Nome-Valore.

     7. Nella sezione Credenziali selezionare il tipo di credenziale di log. Vedere Selezionare il tipo di credenziale per la raccolta dei log API REST.

     8. Per convalidare le informazioni di configurazione immesse, fare clic su Convalida. Se ci sono errori, correggerli.

        Fare clic su Salva modifiche.

   • Per fornire un URL che restituisca una risposta JSON con le informazioni che possono essere utilizzate per generare una lista di URL degli endpoint di log per raccogliere più log, fare clic su Aggiungi endpoint lista per più log. Viene visualizzata la finestra di dialogo Aggiungi endpoint della lista per più log.

     1. Scheda Configura endpoint lista:

        • Immettere il nome endpoint della lista di log.

        • Creare l'URL della lista di log per ottenere le informazioni sui file di log. Vedere URL endpoint lista di log in Tipi di URL endpoint. Ad esempio:

          https://example.org/fetchlogfiles_data

        • Facoltativamente, specificare l'URL del server proxy di log.

        • Selezionare il metodo API GET o POST.

          Se è stato selezionato POST, immettere il payload POST per il metodo e selezionare il tipo di contenuto della richiesta da JSON, Text, Javascript, HTML e XML.

        • Facoltativamente, fare clic su Mostra intestazioni richiesta per espandere la sezione e fare clic su Aggiungi per fornire le intestazioni delle richieste sotto forma di coppie Nome-Valore.

        • Facoltativamente, fare clic su Mostra parametri di query per espandere la sezione e fare clic su Aggiungi per fornire eventuali parametri di query sotto forma di coppie Nome-Valore.

        • Nella sezione Credenziali selezionare il tipo di credenziale di log. Vedere Selezionare il tipo di credenziale per la raccolta dei log API REST.

        • Fare clic su Avanti.

     2. Scheda Configura endpoint log:

        • Fornire la risposta di esempi dell'endpoint della lista di log. Questo è l'esempio della risposta che si ottiene per l'endpoint della lista di log fornito nella scheda precedente. Ad esempio:

          { "totalSize": 4, "records": [ {"id": "firstId", "type": "firstType"}, {"id": "secondId", "type": "secondType"} ] }

          Nell'esempio precedente è possibile utilizzare il percorso JSON records[*].id nell'URL dell'endpoint. Per ulteriori dettagli sulle variabili di percorso JSON, vedere Variabili per la raccolta di log API REST.

        • Immettere il nome endpoint di log.

        • Creare l'URL di log per raccogliere periodicamente i log incorporando le chiavi di percorso JSON identificate nella risposta di esempio all'endpoint della lista di log. Vedere URL endpoint di log in Tipi di URL endpoint. Ad esempio:

          https://example.org/fetchLogs?time={START_TIME}&id={testLogListEP:$.records[*].id}

        • Facoltativamente, specificare l'URL del server proxy di log.

        • Selezionare il metodo API GET o POST.

          Se è stato selezionato POST, immettere il payload POST per il metodo e selezionare il tipo di contenuto della richiesta da JSON, Text, Javascript, HTML e XML.

        • Facoltativamente, specificare l'URL del server proxy di log.

        • Facoltativamente, fare clic su Mostra intestazioni richiesta per espandere la sezione e fare clic su Aggiungi per fornire le intestazioni delle richieste sotto forma di coppie Nome-Valore.

        • Facoltativamente, fare clic su Mostra parametri di query per espandere la sezione e fare clic su Aggiungi per fornire eventuali parametri di query sotto forma di coppie Nome-Valore.

        • Nella sezione Credenziali selezionare il tipo di credenziale di log. Vedere Selezionare il tipo di credenziale per la raccolta dei log API REST.

        • Fare clic su Avanti.

     3. Scheda Rivedi e aggiungi: le informazioni di configurazione fornite nelle schede precedenti vengono convalidate. Verificare la lista di URL da cui verranno raccolti i log.

        Se ci sono errori, correggerli.

        Fare clic su Salva.

8. Fare clic su Crea origine.

URL endpoint della lista di log: l'URL dell'endpoint della lista di log deve restituire una risposta JSON con le informazioni che possono essere utilizzate per creare una lista di URL dell'endpoint di log per raccogliere i log. Specificare le variabili di percorso JSON necessarie per creare la lista di endpoint di log dalla risposta JSON. Inoltre, è possibile utilizzare le macro {START_TIME} e {CURR_TIME} per inserire dinamicamente i valori temporali corrispondenti nell'URL.

URL endpoint di log: l'URL dell'endpoint di log viene utilizzato per raccogliere i log da un endpoint API REST specifico a intervalli regolari. È possibile utilizzare le macro {START_TIME}, {CURR_TIME} e {TIME_WINDOW} per inserire dinamicamente i valori di tempo corrispondenti nell'URL. È possibile utilizzare la macro {OFFSET} per supportare l'impaginazione. È inoltre possibile utilizzare variabili di percorso JSON dalla risposta della chiamata dell'endpoint della lista di log per sostituire proprietà specifiche.

• {START_TIME}: consente di specificare l'ora a partire dalla quale devono essere raccolti i log
• {OFFSET}: per gestire la raccolta di log con paginazione
• {CURR_TIME}: per fornire l'ora corrente
• {TIME_WINDOW}: consente di specificare un intervallo o una durata di raccolta

Per ulteriori informazioni sull'uso delle macro, vedere START_TIME Macro, CURR_TIME Macro, OFFSET Macro e TIME_WINDOW Macro.

Per ulteriori informazioni sull'uso delle variabili dalla risposta dell'endpoint della lista di log che è possibile specificare nell'URL dell'endpoint di log, negli esempi di percorso JSON e nell'uso dei filtri delle variabili, vedere Variabili per la raccolta dei log delle API REST.

Utilizzare la macro START_TIME per specificare l'ora a partire dalla quale devono essere raccolti i log. La macroSTART_TIME può essere utilizzata in un URL endpoint, parametri del form o payload POST.

L'esempio riportato di seguito mostra l'URL dell'endpoint che raccoglie i log con un indicatore orario maggiore di quello specificato dalla macro START_TIME.

https://example.org/fetchLogs?sortBy=timestamp&sortOrder=ascending&filter=timestamp+gt+{START_TIME:yyyy-MM-dd'T'HH:mm:ss.SSSZ}

Sintassi:

{START_TIME<+nX>:<epoch | timestamp format supported by SimpleDateFormat java class>.TZ=<timezone name>}

• n è il valore ora dell'intervallo di date. La X è espressa in giorni (D), ore (h), minuti (m), mesi (M), anno (Y).

• +nX indica il numero di giorni, ore, minuti, mesi o anni da aggiungere all'ora di inizio. È facoltativo. Ad esempio, +3D.

• I formati orari supportati sono gli stessi della classe java SimpleDateFormat. Il formato dell'ora predefinito è yyyy-MM-dd'T'HH:mm:ss.SSSZ. Ad esempio, 2001-07-04T12:08:56.235-0700.

  L'indicazione del formato epoch o dell'ora è facoltativa. Se viene fornita un'epoca, la macro viene sostituita con un valore di millisecondo dell'epoca.

  Per i formati di indicatore orario supportati da SimpleDateFormat, vedere Java Platform Standard Ed. 8: Classe SimpleDateFormat.

• TZ indica il fuso orario dell'indicatore orario. Non è applicabile se l'epoca è già stata fornita. Il formato supportato è lo stesso degli ID di 3 lettere nella classe java TimeZone, ad esempio UTC.

• È possibile includere più istanze di questa macro nell'URL.

• Esempi:

  1. {START_TIME:yyyy-MM-dd'T'HH:mm:ss.SSS.TZ=UTC}
  2. {START_TIME:epoch}

Il valore della macro START_TIME viene determinato in uno dei modi seguenti:

• Quando la raccolta viene avviata per la prima volta per un endpoint, START_TIME è la data cronologica basata sulla proprietà di raccolta agente Dati cronologici. Il valore predefinito di questa proprietà è 30 days, ovvero il valore dell'indicatore orario è 30 giorni prima dell'indicatore orario corrente.

• Se il campo Time è impostato nel parser, nelle raccolte di log successive il valore START_TIME è il valore massimo del valore dell'indicatore orario estratto nella raccolta di log precedente.

• Se il campo Time non viene estratto dai record di log impostandolo nel parser, l'indicatore orario corrente corrisponde al valore START_TIME.

Se nell'API sono presenti filtri, utilizzare greater than equal to anziché greater than per assicurarsi che vengano caricati tutti i record di log con lo stesso indicatore orario.

Utilizzare la macro CURR_TIME per inserire l'ora corrente nell'URL dell'endpoint API REST, nei parametri del form e nel payload POST.

L'esempio riportato di seguito mostra l'URL dell'endpoint che utilizza la macro CURR_TIME nel parametro di query.

https://example.org/fetchLogs?sortBy=timestamp&sortOrder=ascending&time={CURR_TIME:yyyy-MM-dd'T'HH:mm:ss.SSSZ}

• Il formato per l'utilizzo della macro è lo stesso della macro START_TIME.

• È possibile includere più istanze di questa macro nell'URL.

Utilizzare la macro OFFSET per gli endpoint che forniscono risposte impaginate o per gestire il funzionamento dell'offset in una risposta API. La macro OFFSET può essere utilizzata nell'URL dell'endpoint API REST, nei parametri del form e nel payload POST per recuperare più pagine o chunk in un singolo ciclo di raccolta log.

Formato: {OFFSET(<start value>, <increment>)}

• La macro OFFSET viene utilizzata per richiamare e raccogliere i dati in modo iterativo sui risultati impaginati di un endpoint di log specifico per ottenere tutti i record disponibili. La chiamata di richiesta API REST iniziale inizia con il valore di inizio e viene incrementata in ogni chiamata successiva dal valore incremento. Queste chiamate ricorsive basate su indice vengono interrotte quando non sono state trovate altre voci di log. L'offset non viene riportato al ciclo di raccolta successivo. Inizia dal valore predefinito o iniziale in ogni ciclo di raccolta.

• Nel formato precedente, il valore iniziale è il valore iniziale dell'indice e il valore predefinito è 0. È facoltativo specificare il valore iniziale.

  Valori possibili: numero intero positivo compreso 0

• Nel formato precedente, incremento specifica il valore da aggiungere al valore iniziale nelle chiamate successive. Il valore predefinito è 1. È facoltativo specificare il valore incremento.

  Valori possibili: solo numero intero positivo. Escludi 0.

• Nell'URL è possibile includere solo un'istanza di questa macro.

Gli esempi seguenti mostrano diversi modi di utilizzare la macro OFFSET:

• {OFFSET}

  Utilizza i valori predefiniti valore iniziale = 0, incremento = 1.

• {OFFSET(5)}

  valore di inizio = 5, incremento = 1 (predefinito)

• {OFFSET(5,2)}

  valore di inizio = 5, incremento = 2

L'esempio riportato di seguito mostra l'URL dell'endpoint che utilizza la macro OFFSET.

https://example.org/fetchLogs?startIndex={OFFSET(0,1000)}&count=1000

Nell'esempio precedente, OFFSET(0,1000) indica che il valore iniziale è 0 nella prima chiamata e quindi nelle chiamate successive, incrementato di 1000. Pertanto, quando la macro OFFSET viene interpretata, l'URL dell'endpoint per più chiamate sarà il seguente:

Prima chiamata: https://example.org/fetchLogs?startIndex=0&count=1000

Seconda chiamata: https://example.org/fetchLogs?startIndex=1000&count=1000

Utilizzare la macro TIME_WINDOW per specificare l'intervallo di raccolta in base al quale devono essere raccolti i log. Può essere utilizzato nell'URL dell'endpoint API REST per recuperare i log in minuti, ore o giorni, indipendentemente dall'intervallo di raccolta dell'agente. Ad esempio, se la finestra temporale è 1d (un giorno) e l'intervallo dell'agente è di 10 minuti, la raccolta dei log successiva viene eseguita solo dopo un giorno.

L'esempio riportato di seguito imposta l'intervallo di raccolta dei log per 6 ore specificando TIME_WINDOW come 6h nell'URL dell'endpoint.

https://example.org/fetchLogs?timewindow={TIME_WINDOW(6h)}

Formato: {TIME_WINDOW(<number><timeunit>)}

Nel formato precedente:

• numero: numero di cifra maggiore di zero.

• unità di tempo: h per ore, d per giorni, m per minuti. Il valore predefinito è d (giorni).

Assicurarsi che l'intervallo di raccolta dell'agente sia inferiore alla finestra temporale fornita. È possibile utilizzare la macro TIME_WINDOW una sola volta nell'endpoint.

Utilizzare le variabili per sostituire gli attributi forniti come parte della risposta dall'endpoint della lista di log nella richiesta dell'endpoint di log in modo dinamico in fase di esecuzione. Le variabili possono essere utilizzate nell'URL, nei parametri del form, nel payload POST o nei valori di intestazione della richiesta HTTP dell'endpoint di log.

Se la chiamata all'endpoint della lista di log non riesce, i messaggi di log dell'endpoint di log non vengono raccolti a causa della dipendenza.

Formato della variabile nell'endpoint di log:

{<log_list_endpoint_name>:<json path(<filter_field_name>='<value>')>}

• Nel formato precedente, log_list_endpoint_name è il nome dell'endpoint della lista di log.

  Il filtro (<filter_field_name>=<value>) è facoltativo. Solo l'attributo corrispondente a filter_field_name viene prelevato dalla risposta JSON dell'endpoint della lista di log e utilizzato nell'endpoint di log. Ad esempio:

  https://www.example.com/log/{foo:$.items[*].links[*].href(rel='self')}

  Per un esempio dettagliato del filtro, vedere Esempio di filtro.

• Per recuperare i valori delle proprietà è supportato solo il tipo di contenuto JSON.

• La stessa variabile può essere specificata più volte.

• Le variabili possono fare riferimento solo agli endpoint di lista validi e non agli endpoint di log.

• Sono supportati i seguenti formati JSON path: Semplice percorso JSON, Array JSON path e Multiple Arrays JSON path.

{
    "foo" : 
    {
        "abc" : "result"
    }
}

{
    "foo" : {
        "id" : "id1"
    },
    "foo2" : {
        "ID" : "id2",
        "id" : "id3"
    }
}

{
    "foo" : {
        "id" : "id1",
        "abcd" : "value1"
    },
    "foo2" : {
        "id" : "id2"
    }
}

{
     "records": [
         {"id": "firstId", "type":"firstType"},
         {"id":"secondId", "type":"secondType"}
     ],
     "items": [
         {"name":"firstName", "field":"value"},
         {"name":"secondName", "field":"value"},
         {"name":"thirdName", "field":"value"}
     ]
}

https://www.example.com/url_list

{
  "records": [ { "id": "firstId", "type": "firstType" }, { "id": "secondId", "type": "secondType" } ],
  "items": [ { "name": "firstName", "field": "value" }, { "name": "secondName", "field": "value" }, { "name": "thirdName", "field": "value" } ]
}

https://www.example.com/{getlist:$.records[*].id}/{getlist:$.items[*].name}

{
    "items": [
        {
            "BusinessEventCode": "JournalBatchApproved",
            "CreationDate": "2019-07-27T17:19:19.261+00:00",
            "links": [
                {
                    "rel": "self",
                    "href": "/erpBusinessEvents/self/100100120766717"
                },
                {
                    "rel": "canonical",
                    "href": "/erpBusinessEvents/rel/100100120766717"
                }
            ]
        }
    ]
}

https://www.example.com/log/{foo:$.items[*].links[*].href(rel='self')}

https://www.example.com/log/erpBusinessEvents/self/100100120766717

Per autorizzare una connessione tra l'agente e l'origine API REST, configurare innanzitutto la credenziale API nell'area di memorizzazione delle credenziali dell'agente. Dopo aver configurato le credenziali di origine nel servizio Management Agent lato agente, è possibile utilizzare queste informazioni durante la creazione dell'origine log dell'API REST.

Per configurare le credenziali di origine nel servizio Management Agent in modo che il Management Agent possa raccogliere dati dall'host di uscita dal log, vedere Credenziali di origine Management Agent.

Durante l'aggiunta dell'endpoint di log o dell'endpoint della lista di log, fornire le informazioni sulle credenziali nel workflow selezionando il tipo di credenziale di log. Selezionare una delle opzioni riportate di seguito.

• Nessuno
• Autorizzazione di base: specificare il nome della credenziale di log della credenziale creata nel servizio Management Agent.
• Token statico: specificare il nome della credenziale di log della credenziale creata nel servizio Management Agent.
• Token dinamico (OAuth 2.0):

  Specificare il nome credenziale token del token creato nel servizio Management Agent. Fornire inoltre le informazioni sul token, ad esempio Nome endpoint token, URL endpoint token, Tipo di concessione e, facoltativamente, Ambito.

  Se il proxy del token è uguale a quello dell'endpoint di log, mantenere abilitata la casella di controllo Proxy same as log endpoint. In caso contrario, disabilitare la casella di controllo e fornire l'URL del server proxy token.

Mapping dei tipi di credenziali al tipo di autenticazione:

In ssl truststore, proprietà sono incluse le informazioni riportate di seguito.

• "ssl_trustStoreType": tipo di negozio, ad esempio JKS.

• "ssl_trustStoreLocation": il percorso del truststore

• "ssl_trustStorePassword": password del truststore (facoltativo)

Tenere presenti gli aspetti riportati di seguito relativi agli attributi nel file JSON delle credenziali.

• source: il valore deve essere lacollector.la_rest_api

• name: qualsiasi nome appropriato per la credenziale in uno dei seguenti formati.

  • <cred_name>.<entity_name>: nome credenziale con nome entità
  • <nome credenziale>: solo nome credenziale

  L'agente cerca il nome nel primo formato. Se non trovato, cerca il nome nel secondo formato.

• type: deve essere uno dei valori specificati nella colonna Tipo di credenziale in Management Agent nella tabella dei tipi di credenziale precedente.

Vedere Esempi di notazione JSON delle credenziali.

{
  "source":"lacollector.la_rest_api",
  "name":"ExampleRestAPICreds",
  "type":"HTTPSBasicAuthCreds",
  "description":"These are HTTPS (BasicAuth) credentials.",
  "properties":
  [
    { "name":"HTTPSUserName", "value":"CLEAR[admin]" },
    { "name":"HTTPSPassword", "value":"CLEAR[myHTTPSPassword]" }
  ]
}

{
  "source":"lacollector.la_rest_api",
  "name":"ExampleRestAPICreds",
  "type":"HTTPSCreds",
  "description":"These are HTTPS (BasicAuth) credentials.",
  "properties":
  [
    { "name":"HTTPSUserName", "value":"CLEAR[admin]" },
    { "name":"HTTPSPassword", "value":"CLEAR[myHTTPSPassword]" },
    { "name":"ssl_trustStoreType", "value":"JKS" },
    { "name":"ssl_trustStoreLocation", "value":"/scratch/certs/mycert.keystore" },
    { "name":"ssl_trustStorePassword", "value":"mySSLPassword" }
  ]
}

{
  "source":"lacollector.la_rest_api",
  "name":"ExampleRestAPICreds",
  "type":"HTTPSTokenCreds",
  "description":"These are HTTPS (Token) credentials.",
  "properties":
  [
    { "name": "HTTPSToken", "value": "CLEAR[token value]" },
    {"name": "HTTPSTokenType", "value": "CLEAR[Bearer]" }
  ]
}

{
  "source":"lacollector.la_rest_api",
  "name":"ExampleRestAPICreds",
  "type":"HTTPSTokenCreds",
  "description":"These are HTTPS (Token) credentials.",
  "properties":
  [
    { "name": "HTTPSToken", "value": "CLEAR[token value]" },
    {"name": "HTTPSTokenType", "value": "CLEAR[Bearer]" },
    { "name":"ssl_trustStoreType", "value":"JKS" },
    { "name":"ssl_trustStoreLocation", "value":"/scratch/certs/mycert.keystore" },
    { "name":"ssl_trustStorePassword", "value":"mySSLPassword" }
  ]
}

Attenersi alla procedura riportata di seguito per raccogliere i log di audit di Fusion Applications. Per l'elenco delle origini definite da Oracle disponibili per Fusion Applications, vedere Origini definite da Oracle.

Argomenti:

• Requisiti indispensabili
• Imposta raccolta log di audit da Fusion Applications