Configuration de la collecte de journaux d'API REST

Oracle Log Analytics fournit déjà une source de journal définie par Oracle pour la collecte de journaux d'API REST. Vérifiez si vous pouvez utiliser la source d'API REST définie par Oracle disponible ou tout analyseur défini par Oracle. Sinon, procédez comme suit pour créer une source de journal :

Avant de commencer, si vous devez créer un analyseur adapté à vos journaux, complétez-le. Reportez-vous à Création d'un analyseur.

1. Ouvrez le menu de navigation et cliquez sur Observation et gestion. Sous Log Analytics, cliquez sur Administration. La page Présentation de l'administration apparaît.

   Les ressources d'administration sont répertoriées dans le panneau de navigation de gauche sous Ressources. Cliquez sur Sources.

2. La page Sources apparaît. Cliquez sur Créer une source.

   La boîte de dialogue Créer une source apparaît.

3. Dans le champ Nom, entrez le nom de la source de journal.

4. Dans la liste Type de source, sélectionnez API REST.

5. Cliquez sur Type d'entité, puis sélectionnez le type qui identifie le mieux votre application.

6. Cliquez sur Analyseur et sélectionnez un analyseur approprié pour le type de journal à collecter.

7. Dans l'onglet Adresses, cliquez sur Ajouter une adresse de journal ou Ajouter une adresse de liste pour plusieurs journaux en fonction de vos besoins :

   • Pour fournir une URL d'adresse de journal unique à l'aide de laquelle les journaux peuvent être collectés en continu, cliquez sur Ajouter une adresse de journal. La boîte de dialogue Ajouter une adresse de journal s'ouvre.

     Entrez les informations suivantes :

     1. Entrez le nom de l'adresse de journal.

     2. Créez l'URL de journal pour collecter les journaux régulièrement. Reportez-vous à URL d'adresse de journal dans Types d'URL d'adresse.

     3. Sélectionnez la méthode d'API GET ou POST.

        Si vous avez sélectionné POST, entrez la charge utile POST de la méthode et sélectionnez le type de contenu de demande dans JSON, Text, Javascript, HTML et XML.

     4. Vous pouvez éventuellement indiquer l'URL du serveur proxy de journal.

     5. Vous pouvez également cliquer sur Afficher les en-têtes de demande pour développer la section, puis sur Ajouter pour fournir des en-têtes de demande sous la forme de paires Nom-Valeur.

     6. Vous pouvez également cliquer sur Afficher les paramètres de requête pour développer la section, puis sur Ajouter pour fournir des paramètres de requête sous la forme de paires Nom-Valeur.

     7. Dans la section Informations d'identification, sélectionnez le type d'informations d'identification de journal. Reportez-vous à Sélection du type d'informations d'identification pour la collecte de journaux d'API REST.

     8. Pour valider les informations de configuration saisies, cliquez sur Valider. En cas d'erreurs, corrigez-les.

        Cliquez sur Enregistrer les modifications.

   • Pour fournir une URL qui renvoie une réponse JSON avec les informations pouvant être utilisées pour générer la liste des URL d'adresse de journal afin de collecter plusieurs journaux, cliquez sur Ajouter une adresse de liste pour plusieurs journaux. La boîte de dialogue Ajouter une adresse de liste pour plusieurs journaux s'ouvre.

     1. Onglet Configurer l'adresse de liste :

        • Entrez le nom de l'adresse de liste de journaux.

        • Créez l'URL de liste de journaux pour obtenir les informations sur les fichiers journaux. Reportez-vous à URL d'adresse de liste de journaux dans Types d'URL d'adresse. Par exemple :

          https://example.org/fetchlogfiles_data

        • Vous pouvez éventuellement indiquer l'URL du serveur proxy de journal.

        • Sélectionnez la méthode d'API GET ou POST.

          Si vous avez sélectionné POST, entrez la charge utile POST de la méthode et sélectionnez le type de contenu de demande dans JSON, Text, Javascript, HTML et XML.

        • Vous pouvez également cliquer sur Afficher les en-têtes de demande pour développer la section, puis sur Ajouter pour fournir des en-têtes de demande sous la forme de paires Nom-Valeur.

        • Vous pouvez également cliquer sur Afficher les paramètres de requête pour développer la section, puis sur Ajouter pour fournir des paramètres de requête sous la forme de paires Nom-Valeur.

        • Dans la section Informations d'identification, sélectionnez le type d'informations d'identification de journal. Reportez-vous à Sélection du type d'informations d'identification pour la collecte de journaux d'API REST.

        • Cliquez sur Suivant.

     2. Onglet Configurer l'adresse de journal :

        • Indiquez l'exemple de réponse de l'adresse de liste de journaux. Voici l'exemple de réponse que vous obtiendrez pour l'adresse de liste de journaux que vous avez fournie dans l'onglet précédent. Par exemple :

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

          Dans l'exemple ci-dessus, le chemin JSON records[*].id peut être utilisé dans l'URL d'adresse. Pour plus de détails sur les variables de chemin JSON, reportez-vous à Variables pour la collecte de journaux d'API REST.

        • Entrez le nom de l'adresse de journal.

        • Créez l'URL de journal pour collecter les journaux régulièrement en intégrant les clés de chemin JSON identifiées dans l'exemple de réponse à l'adresse de liste de journaux. Reportez-vous à URL d'adresse de journal dans Types d'URL d'adresse. Par exemple :

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

        • Vous pouvez éventuellement indiquer l'URL du serveur proxy de journal.

        • Sélectionnez la méthode d'API GET ou POST.

          Si vous avez sélectionné POST, entrez la charge utile POST de la méthode et sélectionnez le type de contenu de demande dans JSON, Text, Javascript, HTML et XML.

        • Vous pouvez éventuellement indiquer l'URL du serveur proxy de journal.

        • Vous pouvez également cliquer sur Afficher les en-têtes de demande pour développer la section, puis sur Ajouter pour fournir des en-têtes de demande sous la forme de paires Nom-Valeur.

        • Vous pouvez également cliquer sur Afficher les paramètres de requête pour développer la section, puis sur Ajouter pour fournir des paramètres de requête sous la forme de paires Nom-Valeur.

        • Dans la section Informations d'identification, sélectionnez le type d'informations d'identification de journal. Reportez-vous à Sélection du type d'informations d'identification pour la collecte de journaux d'API REST.

        • Cliquez sur Suivant.

     3. Onglet Vérifier et ajouter : les informations de configuration fournies dans les onglets précédents sont validées. Vérifiez la liste des URL à partir desquelles les journaux seront collectés.

        En cas d'erreurs, corrigez-les.

        Cliquez sur Enregistrer.

8. Cliquez sur Créer une source.

URL d'adresse de liste de journaux : l'URL d'adresse de liste de journaux doit renvoyer une réponse JSON avec les informations qui peuvent être utilisées pour construire une liste d'URL d'adresse de journal afin de collecter les journaux. Indiquez les variables de chemin JSON requises pour créer la liste des adresses de journal à partir de la réponse JSON. En outre, vous pouvez utiliser les macros {START_TIME} et {CURR_TIME} pour insérer dynamiquement les valeurs temporelles correspondantes dans l'URL.

URL d'adresse de journal : l'URL d'adresse de journal est utilisée pour collecter des journaux à partir d'une adresse d'API REST spécifique à intervalles réguliers. Vous pouvez utiliser les macros {START_TIME}, {CURR_TIME} et {TIME_WINDOW} pour insérer dynamiquement les valeurs d'heure correspondantes dans l'URL. La macro {OFFSET} peut être utilisée pour prendre en charge la pagination. Vous pouvez également utiliser des variables de chemin JSON à partir de la réponse de l'appel d'adresse de liste de journaux pour remplacer des propriétés spécifiques.

• {START_TIME} : pour indiquer l'heure à partir de laquelle les journaux doivent être collectés
• {OFFSET} : pour gérer la collecte de journaux paginée
• {CURR_TIME} : pour indiquer l'heure actuelle
• {TIME_WINDOW} : pour indiquer un intervalle ou une durée de collecte

Pour plus d'informations sur l'utilisation des macros, reportez-vous à START_TIME Macro, CURR_TIME Macro, OFFSET Macro et TIME_WINDOW Macro.

Pour plus d'informations sur l'utilisation des variables de la réponse d'adresse de liste de journaux pouvant être indiquée dans l'URL d'adresse de journal, des exemples de chemin JSON et l'utilisation de filtres de variable, reportez-vous à Variables pour la collecte de journaux d'API REST.

Utilisez la macro START_TIME pour indiquer l'heure à partir de laquelle les journaux doivent être collectés. La macro START_TIME peut être utilisée dans une URL d'adresse, des paramètres de formulaire ou une charge utile POST.

L'exemple suivant illustre l'URL d'adresse qui collecte les journaux supérieurs à un horodatage spécifié par la macro START_TIME :

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

Syntaxe :

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

• n est la valeur temporelle de la plage de dates. X est exprimé en jours (D), heures (h), minutes (m), mois (M), année (Y).

• +nX représente le nombre de jours, d'heures, de minutes, de mois ou d'années à ajouter à l'heure de début. Elle est facultative. Par exemple, +3D.

• Les formats d'heure pris en charge sont identiques à ceux de la classe java SimpleDateFormat. Le format d'heure par défaut est yyyy-MM-dd'T'HH:mm:ss.SSSZ. Par exemple, 2001-07-04T12 :08 :56.235-0700.

  La spécification du format d'heure ou epoch est facultative. Si epoch est fourni, la macro est remplacée par la valeur epoch millisecond.

  Pour les formats d'horodatage pris en charge par SimpleDateFormat, reportez-vous à Java Platform Standard Ed. 8 : classe SimpleDateFormat.

• TZ permet de fournir le fuseau horaire de l'horodatage. Il n'est pas applicable si epoch est déjà fourni. Le format pris en charge est le même que les ID à 3 lettres de la classe java TimeZone, par exemple UTC.

• Vous pouvez inclure plusieurs instances de cette macro dans l'URL.

• Exemples :

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

La valeur de la macro START_TIME est déterminée de l'une des manières suivantes :

• Lorsque la collecte commence pour la première fois pour une adresse, START_TIME est la date historique basée sur la propriété de collecte d'agent Données historiques. La valeur par défaut de cette propriété est 30 days, c'est-à-dire que la valeur de l'horodatage est antérieure de 30 jours à l'horodatage en cours.

• Si le champ Heure est défini dans l'analyseur, dans les ensembles de journaux suivants, la valeur de START_TIME est la valeur maximale de la valeur d'horodatage extraite dans l'ensemble de journaux précédent.

• Si le champ Heure n'est pas extrait des enregistrements de journal en le définissant dans l'analyseur, l'horodatage en cours est la valeur de START_TIME.

Si l'API contient des filtres, utilisez greater than equal to au lieu de greater than pour vous assurer que tous les enregistrements de journal ayant le même horodatage sont téléchargés.

Utilisez la macro CURR_TIME pour insérer l'heure en cours dans l'URL d'adresse d'API REST, les paramètres de formulaire et la charge utile POST.

L'exemple suivant illustre l'URL d'adresse qui utilise la macro CURR_TIME dans le paramètre de requête :

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

• Le format d'utilisation de la macro est identique à celui de la macro START_TIME.

• Vous pouvez inclure plusieurs instances de cette macro dans l'URL.

Utilisez la macro OFFSET pour les adresses qui fournissent des réponses paginées ou pour gérer le comportement de décalage dans une réponse d'API. La macro OFFSET peut être utilisée dans l'URL d'adresse d'API REST, les paramètres de formulaire et la charge utile POST pour extraire plusieurs pages ou blocs dans un cycle de collecte de journal unique.

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

• La macro OFFSET permet d'appeler et de collecter des données de manière itérative sur les résultats paginés d'une adresse de journal spécifique pour obtenir tous les enregistrements disponibles. L'appel de demande d'API REST initial commence par la valeur de début et est incrémenté dans chaque appel suivant de la valeur incrément. Ces appels basés sur un index récursif sont arrêtés lorsqu'aucune autre entrée de journal n'est trouvée. Le décalage n'est pas reporté au cycle de collecte suivant. Il commence à partir de la valeur par défaut ou initiale de chaque cycle de collecte.

• Dans le format ci-dessus, la valeur de début est la valeur initiale de l'index et la valeur par défaut est 0. Il est facultatif de spécifier une valeur de début.

  Valeurs possibles : entier positif, y compris 0

• Dans le format ci-dessus, incrément spécifie la valeur à ajouter à la valeur de début lors des appels suivants. La valeur par défaut est 1. Il est facultatif de spécifier la valeur incrément.

  Valeurs possibles : Entier positif uniquement. Exclure 0.

• Vous ne pouvez inclure qu'une seule instance de cette macro dans l'URL.

Les exemples suivants illustrent différentes façons d'utiliser la macro OFFSET :

• {OFFSET}

  Utilise les valeurs par défaut valeur de début = 0, incrément = 1.

• {OFFSET(5)}

  valeur de début = 5, incrément = 1 (valeur par défaut)

• {OFFSET(5,2)}

  valeur de début = 5, incrément = 2

L'exemple suivant illustre l'URL d'adresse qui utilise la macro OFFSET :

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

Dans l'exemple ci-dessus, OFFSET(0,1000) indique que la valeur de début est égale à 0 dans le premier appel, puis dans les appels suivants, incrémentés de 1000. Par conséquent, lorsque la macro OFFSET est interprétée, l'URL endpoint pour plusieurs appels est la suivante :

Premier appel : https://example.org/fetchLogs?startIndex=0&count=1000

Deuxième appel : https://example.org/fetchLogs?startIndex=1000&count=1000

Utilisez la macro TIME_WINDOW pour indiquer l'intervalle de collecte sur lequel les journaux doivent être collectés. Elle peut être utilisée dans l'URL d'adresse d'API REST pour extraire des journaux en quelques minutes, heures ou jours, quel que soit l'intervalle de collecte de l'agent. Par exemple, si la fenêtre de temps est 1d (un jour) et que l'intervalle de l'agent est de 10 minutes, la collecte de journal suivante n'a lieu qu'après une journée.

L'exemple suivant définit l'intervalle de collecte de journal pendant 6 heures en indiquant TIME_WINDOW comme 6h dans l'URL d'adresse :

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

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

Au format ci-dessus :

• nombre : nombre numérique supérieur à zéro.

• unité de temps : h pour les heures, d pour les jours et m pour les minutes. La valeur par défaut est d (jours).

Assurez-vous que l'intervalle de collecte de l'agent est inférieur à la fenêtre de temps indiquée. Vous ne pouvez utiliser la macro TIME_WINDOW qu'une seule fois dans l'adresse.

Utilisez les variables pour remplacer les attributs fournis dans le cadre de la réponse de l'adresse de liste de journaux dans la demande de l'adresse de journal de manière dynamique lors de l'exécution. Les variables peuvent être utilisées dans l'URL, les paramètres de formulaire, la charge utile POST ou les valeurs d'en-tête de demande HTTP de l'adresse de journal.

Si l'appel de l'adresse de liste de journaux échoue, les messages de journal de l'adresse de journal ne sont pas collectés en raison de la dépendance.

Format de la variable dans l'adresse de journal :

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

• Au format ci-dessus, log_list_endpoint_name est le nom de l'adresse de liste de journaux.

  Le filtre (<filter_field_name>=<value>) est facultatif. Seul l'attribut correspondant à filter_field_name est extrait de la réponse JSON de l'adresse de liste de journaux et utilisé dans l'adresse de journal. Par exemple :

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

  Pour obtenir un exemple détaillé du filtre, reportez-vous à Exemple de filtre.

• Seul le type de contenu JSON est pris en charge pour extraire les valeurs de propriété.

• La même variable peut être spécifiée plusieurs fois.

• Les variables peuvent uniquement faire référence à des adresses de liste valides et non à des adresses de journal.

• Les formats de chemin JSON suivants sont pris en charge : chemin JSON simple, chemin JSON de tableau et chemin JSON de tableaux multiples.

{
    "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

Pour autoriser une connexion entre l'agent et la source d'API REST, configurez d'abord les informations d'identification d'API dans la banque d'informations d'identification de l'agent. Après avoir configuré les informations d'identification source dans le service Management Agent côté agent, vous pouvez utiliser ces informations lors de la création de la source de journal d'API REST.

Pour configurer les informations d'identification source dans le service d'agent de gestion afin de permettre à l'agent de gestion de collecter des données à partir de l'hôte émetteur de journaux, reportez-vous à Informations d'identification source de l'agent de gestion.

Lors de l'ajout de l'adresse de journal ou de la liste de journaux, fournissez les informations d'identification dans le workflow en sélectionnant le type d'informations d'identification de journal. Sélectionnez l'une des options suivantes :

• Aucun
• Authentification de base : indiquez le nom des informations d'identification de journal des informations d'identification que vous avez créées dans le service d'agent de gestion.
• Jeton statique : indiquez le nom des informations d'identification de journal des informations d'identification créées dans le service d'agent de gestion.
• Jeton dynamique (OAuth 2.0):

  Indiquez le nom des informations d'identification de jeton du jeton que vous avez créé dans le service d'agent de gestion. En outre, fournissez les informations de jeton telles que Nom d'adresse de jeton, URL d'adresse de jeton, Type d'octroi et éventuellement Portée.

  Si le proxy de jeton est identique à celui de l'adresse de journal, conservez la case Proxy identique à l'adresse de journal activée. Dans le cas contraire, désactivez la case à cocher et indiquez l'URL du serveur proxy de jeton.

Mappage des types d'informations d'identification avec le type d'authentification :

Les informations suivantes sont incluses dans les propriétés de truststore sssl :

• "ssl_trustStoreType" : type de stockage, par exemple, JKS.

• "ssl_trustStoreLocation" : chemin du truststore

• "ssl_trustStorePassword" : mot de passe du truststore (facultatif)

Tenez compte des aspects suivants concernant les attributs dans le fichier JSON des informations d'identification :

• source : la valeur doit être lacollector.la_rest_api

• name : nom approprié pour les informations d'identification

• type : il doit s'agir de l'une des valeurs indiquées sous la colonne Type d'informations d'identification à l'agent OMA dans la table des types d'informations d'identification ci-dessus.

Reportez-vous à Exemples d'informations d'identification au format JSON.

{
  "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" }
  ]
}

Suivez ces étapes pour collecter les journaux d'audit Fusion Applications. Pour la liste des sources définies par Oracle disponibles pour Fusion Applications, reportez-vous à Sources définies par Oracle.

Rubriques :

• Prérequis
• Configurer la collecte des journaux d'audit à partir de Fusion Applications