Scénario C : enregistrement de tickets Jira pour les rappels

Enregistrez automatiquement un ticket Jira chaque fois qu'un événement de rappel de maintenance se produit. Dans ce scénario, chaque fois qu'un rappel de maintenance de base de données à venir provient d'Oracle Cloud Infrastructure, un ticket Jira est créé pour l'ingénieur sur appel.

Ce scénario implique l'écriture d'une fonction dans le fichier de tickets Jira (et la création d'un secret pour stocker les informations d'identification Jira), l'ajout de cette fonction et de ce courriel facultatif en tant qu'abonnements à un sujet , ainsi que la création d'une règle qui envoie des messages à cette rubrique lorsque des événements de rappel de maintenance surviennent (reportez-vous à Types d'événement de base de données Conteneur Autonomous). Le message est transféré vers les abonnements du sujet, qui inclut une adresse électronique de groupe en plus de la fonction. La fonction est appelée à la réception du message.

Tout sauf la fonction peut être configuré dans la console. Sinon, vous pouvez utiliser l'interface de ligne de commande ou l'API Oracle Cloud Infrastructure, qui vous permettent d'exécuter chaque opération vous-même.

Remarque

Le service Notifications ne dispose d'aucune information sur une fonction après que celle-ci a été appelée. Pour plus de détails, reportez-vous aux informations de dépannage dans Fonction non appelée ou non exécutée.

Cette image présente Notifications dans le contexte d'un scénario qui utilise une fonction pour enregistrer des tickets Jira lorsque des événements de rappel se produisent.

Pour plus d'informations sur ce scénario, reportez-vous à Création automatisée de tickets Jira à l'aide d'OCI Events, Notifications et Functions et au référentiel GitHub associé.

Stratégie IAM requise

Pour utiliser Oracle Cloud Infrastructure, un administrateur doit vous accorder un accès sécurisé dans une stratégie. Cet accès est requis, que vous utilisiez la console ou l'API REST avec un kit SDK, une interface de ligne de commande ou un autre outil. Si un message vous indique que vous ne disposez pas des droits d'accès ou des autorisations nécessaires, vérifiez auprès de l'administrateur le type d'accès qui vous a été accordé et le compartiment dans lequel vous devez travailler.

Si vous êtes membre du groupe Administrateurs, vous disposez déjà de l'accès requis pour exécuter ce scénario. Sinon, vous devez accéder à Events, Notifications et Functions. Vous devez disposer du droit d'accès FN_INVOCATION sur la fonction afin de pouvoir l'ajouter en tant qu'abonnement à un sujet. Pour accéder à vos informations d'identification Jira, la fonction doit être autorisée à lire les clés secrètes. Ce scénario parcourt les étapes permettant de fournir cette autorisation.

Tâche 1 : stocker les informations d'identification dans une clé secrète

Pour plus d'informations sur la création de clés secrètes à l'aide du service Vault, reportez-vous à Création d'une clé secrète dans un coffre.

    1. Ouvrez le menu de navigation, cliquez sur Identité et sécurité, puis cliquez sur Coffre.
    2. Sous Portée de la liste, dans la liste Compartiment, sélectionnez le nom du compartiment dans lequel créer la clé secrète.
    3. Dans la liste des coffres du compartiment, effectuez l'une des opérations suivantes :

      • Sélectionnez le nom du coffre dans lequel créer la clé secrète.

      • Créez un coffre pour la clé secrète en suivant les instructions dans Procédure de création d'un coffre, puis sélectionnez le nom du coffre.

    4. Sélectionnez Clés secrètes, puis Créer une clé secrète.
    5. Dans le panneau Créer une clé secrète, choisissez un compartiment dans la liste Créer dans le compartiment. (Les clés secrètes peuvent exister en dehors du compartiment dans lequel se trouve le coffre.)
    6. Entrez un nom pour identifier la clé secrète. Evitez de saisir des informations confidentielles.

      Exemple de nom : jira_auth_plain_text

    7. Saisissez une description succincte de la clé secrète pour vous aider à l'identifier. Evitez de saisir des informations confidentielles.

      Exemple de description : jira_auth_plain_text

    8. Choisissez la clé de cryptage maître à utiliser pour crypter le contenu de la clé secrète pendant l'import vers le coffre. (La clé doit appartenir au même coffre.)
    9. Pour Modèle de type de clé secrète, sélectionnez Texte brut.
    10. Pour Contenu de clé secrète, entrez vos informations d'identification Jira au format suivant, en séparant votre adresse électronique de connexion de votre jeton d'authentification par le signe deux-points :

      <your-jira-cloud-login-email>:<your-jira-cloud-auth-token>

    11. Sélectionnez Créer une clé secrète.
    12. Notez l'OCID de clé secrète à utiliser dans le code de fonction pour extraire la clé secrète en toute sécurité.
  • Remarque

    Vous devez indiquer une clé symétrique pour crypter la clé secrète lors de l'import vers le coffre. Vous ne pouvez pas crypter des clés secrètes avec des clés asymétriques. En outre, la clé doit exister dans le coffre que vous indiquez.

    Utilisez la commande oci vault secret create-base64 et les paramètres requis pour créer une clé secrète stockant vos informations d'identification Jira :

    oci vault secret create-base64 --compartment-id <target_compartment_id> --secret-name <secret_name> --vault-id <target_vault_id> --description <secret_description_text> --key-id <encryption_key_id> --secret-content-content <base64_encoded_secret_content> --secret-content-name <unique_content_name> --secret-content-stage <secret_version_rotation_state>

    Pour obtenir la liste complète des paramètres et des valeurs des commandes d'interface de ligne de commande, reportez-vous à Référence de commande d'interface de ligne de commande.

  • Exécutez l'opération CreateSecret pour créer une clé secrète.

    Exemple :

    POST /20180608/secrets
    Host: <managementEndpoint>
    <authorization and other headers>
    {
      "vaultId": "<vault_OCID>",
      "compartmentId": "<compartment_OCID>",
      "secretName": "jira_auth_plain_text",
      "description": "jira_auth_plain_text",
      "keyId": "<key_OCID>",
      "secretContent": 
        {
          "content": "<base64_encoded_secret_contents>",
          "contentType": "BASE64"
        }
    }
    Remarque

    Chaque région comporte une adresse unique pour les opérations de création, de mise à jour et de liste des clés secrètes. Cette adresse est appelée URL de plan de contrôle ou adresse de gestion des clés secrètes. Chaque région dispose également d'une adresse unique pour les opérations liées à l'extraction du contenu des clés secrètes. Cette adresse est connue sous le nom d'URL de plan de données ou d'adresse d'extraction des clés secrètes. Pour les adresses régionales, reportez-vous à Documentation relative à l'API.

    Pour plus d'informations sur l'utilisation de l'API et la signature des demandes, reportez-vous à la documentation relative à l'API REST et à Informations d'identification de sécurité. Pour plus d'informations sur les kits SDK, reportez-vous à Kits SDK et interface de ligne de commande.

Tâche 2 : créer la fonction

Cette section fournit l'exemple de code pour la création de la fonction et décrit les étapes permettant d'autoriser la fonction à accéder à vos informations d'identification Jira dans la clé secrète créée à l'aide du service Vault.

Exemple de code de fonction

L'exemple de code suivant concerne une fonction pour enregistrer des tickets Jira.

Ajoutez l'OCID de clé secrète dans la ligne qui inclut getSecretForOcid.

Pour obtenir des instructions sur la création et le déploiement de fonctions, reportez-vous à Création et déploiement de fonctions.

public String handleRequest(CloudEvent cloudEvent) {
 
    // Json body of Cloud event from Oracle Event Service in serialized into cloudEvent object by Fn SDK implicitly
    System.err.println("Inside Java jira function with input as " + cloudEvent.getEventType() + "  " + cloudEvent.getData().getResourceName());
 
    String response = jiraCreateTicket(cloudEvent);
 
    if (response != null) return response;
 
    return null;
}
 
private String jiraCreateTicket(CloudEvent cloudEvent) {
 
    try {
        //create jira ticket body as per CloudEvent
        String jsonBodyJira = getJiraApiBody(cloudEvent);
 
        String jiraCloudEndpoint = System.getenv().get("JIRA_CLOUD_URL");
        String ocidForSecretForJiraAuthToken = System.getenv().get("JIRA_CLOUD_SECRET_OCID");
        String jiraAuthToken= getSecretForOcid(ocidForSecretForJiraAuthToken); // base64 encoded form of <YourJiraUsername:YourJiraAuthToken>
 
        // actual REST call to JIRA cloud
        OkHttpClient client = new OkHttpClient().newBuilder()
                .build();
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType, jsonBodyJira);
        Request request = new Request.Builder()
                .url(jiraCloudEndpoint)
                .method("POST", body)
                .addHeader("Accept", "application/json")
                .addHeader("Content-Type", "application/json")
                .addHeader("Authorization", "Basic "+ jiraAuthToken)
                .build();
        Response response = client.newCall(request).execute();
        return response.body().string();
 
    } catch (JsonProcessingException e) {
        e.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    }
    return null;
}
Autoriser votre fonction à accéder aux clés secrètes

Utilisez un groupe dynamique pour accorder à la fonction la possibilité de lire des clés secrètes. Votre fonction doit disposer de cette autorisation pour accéder à vos informations d'identification Jira, qui sont stockées dans la clé secrète que vous avez créée précédemment.

Pour autoriser votre fonction à accéder aux clés secrètes (console)
  1. Recherchez et notez l'OCID de la fonction (format : ocid1.fnfunc.oc1.iad.exampleuniqueID).
  2. Incluez votre fonction dans un groupe dynamique : dans le groupe dynamique approprié, indiquez la règle suivante :
    resource.id = '<function-ocid>'

    Vous pouvez également créer un groupe dynamique qui inclut toutes les fonctions :

    ALL{resource.type='fnfunc', resource.compartment.id='<compartment_OCID>'}
  3. Accordez à ce groupe l'accès aux clés secrètes : ajoutez la stratégie suivante :
    allow dynamic-group <dynamic-group-name> to read secret-family in tenancy

Pour autoriser la fonction à accéder à d'autres ressources Oracle Cloud Infrastructure, telles que des instances de calcul, incluez la fonction dans un groupe dynamique et créez une stratégie pour accorder au groupe l'accès à ces ressources. Pour plus d'informations, reportez-vous à Accès à d'autres ressources Oracle Cloud Infrastructure à partir de fonctions en cours d'exécution.

Pour plus d'informations sur les groupes dynamiques, reportez-vous à Gestion des groupes dynamiques.

Tâche 3 : créer le sujet

Pour obtenir de l'aide sur le dépannage, reportez-vous à Dépannage de Notifications.

    1. Ouvrez le panneau Créer une rubrique : sur la page de liste Rubriques, sélectionnez Créer une rubrique. Si vous avez besoin d'aide pour trouver la page de liste, reportez-vous à la rubrique Liste des sujets.
    2. Pour Nom, saisissez les informations suivantes : Rubrique de maintenance
    3. Sélectionnez Créer.
  • Utilisez la commande oci ons topic create et les paramètres requis pour créer un sujet :

    oci ons topic create --name <name> --compartment-id <compartment_OCID>

    Exemple :

    oci ons topic create --name "Maintenance Topic" --compartment-id "<compartment-ocid>"

    Afin d'obtenir la liste complète des paramètres et des valeurs des commandes d'interface de ligne de commande, reportez-vous à Référence de ligne de commande pour Notifications.

  • Exécutez l'opération CreateTopic pour créer un sujet.

    Exemple :

    POST /20181201/topics
    Host: notification.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    {
      "name": "Maintenance Topic",
      "compartmentId": "<compartment_OCID>"
    }

Tâche 4 : créer les abonnements

La fonction doit être déployée avant de créer l'abonnement à la fonction.

Pour obtenir de l'aide sur le dépannage, reportez-vous à Dépannage de Notifications.

    1. Sélectionnez le sujet que vous avez créé précédemment (par exemple, Rubrique de maintenance) : sur la page de liste Rubriques, sélectionnez le sujet à utiliser. Si vous avez besoin d'aide pour rechercher la page de liste ou le sujet, reportez-vous à Liste des sujets.
    2. Créez l'abonnement de la fonction.
      1. Ouvrez le panneau Créer un abonnement : sur la page de détails du sujet, sélectionnez Créer un abonnement.
        Le panneau Créer un abonnement apparaît.
      2. Pour Protocole, sélectionnez Fonction.
      3. Renseignez les autres champs.
        Champ Description
        Compartiment de fonction Sélectionnez le compartiment contenant la fonction.
        Application de fonction Sélectionnez l'application contenant la fonction.
        Fonction Sélectionnez la fonction.
      4. Sélectionnez Créer.
        Aucune confirmation n'est nécessaire pour les nouveaux abonnements aux fonctions.
    3. Créez l'abonnement e-mail.
      1. Ouvrez le panneau Créer un abonnement : sur la page de détails du sujet, sélectionnez Créer un abonnement.
        Le panneau Créer un abonnement apparaît.
      2. Pour Protocol, sélectionnez Email.
      3. Renseignez les autres champs.
        Champ Description
        Courriel Saisissez une adresse électronique.
      4. Sélectionnez Créer.
      5. Confirmez le nouvel abonnement par courriel : ouvrez le courriel et accédez à l'URL de confirmation.
  • Remarque

    Une fois l'abonnement par courriel créé, confirmez-le.

    Utilisez la commande oci ons subscription create et les paramètres requis pour créer chaque abonnement :

    oci ons subscription create --protocol <subscription_type> --subscription-endpoint <endpoint> --compartment-id <compartment_OCID> --topic-id <topic_OCID>

    Exemple d'abonnement de fonction :

    oci ons subscription create --protocol "ORACLE_FUNCTIONS" --subscription-endpoint "<function-ocid>" --compartment-id "<compartment_OCID>" --topic-id "<topic_OCID>"

    Exemple d'abonnement aux courriels :

    oci ons subscription create --protocol "EMAIL" --subscription-endpoint "maintenance.team@example.com" --compartment-id "<compartment_OCID>" --topic-id "<topic_OCID>"

    Afin d'obtenir la liste complète des paramètres et des valeurs des commandes d'interface de ligne de commande, reportez-vous à Référence de ligne de commande pour Notifications.

  • Remarque

    Une fois l'abonnement par courriel créé, confirmez-le.

    Exécutez l'opération CreateSubscription pour créer chaque abonnement.

    Exemple d'abonnement de fonction :

    POST /20181201/subscriptions
    Host: notification.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    {
      "topicId": "<topic_OCID>",
      "compartmentId": "<compartment_OCID>",
      "protocol": "ORACLE_FUNCTIONS",
      "endpoint": "<function_OCID>"
    }

    Exemple d'abonnement aux courriels :

    POST /20181201/subscriptions
    Host: notification.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    {
      "topicId": "<topic_OCID>",
      "compartmentId": "<compartment_OCID>",
      "protocol": "EMAIL",
      "endpoint": "maintenance.team@example.com"
    }

Tâche 5 : créer la règle d'événement

  • Cette section explique comment créer la règle qui envoie un message à la rubrique chaque fois que le service Database émet un événement pour un rappel de maintenance de base de données.

    1. Ouvrez le menu de navigation et cliquez sur Observation & gestion. Sous Service d'événements, cliquez sur Règles.
    2. Choisissez un compartiment sur lequel vous êtes autorisé à travailler, puis sélectionnez Créer une règle.

      Events compare les règles que vous créez dans ce compartiment aux messages d'événement émis à partir des ressources de ce compartiment et de tous les compartiments enfant.

    3. Entrez les informations suivantes.
      • Nom d'affichage : indiquez un nom convivial pour la règle. Vous pouvez modifier ce nom ultérieurement. Evitez de saisir des informations confidentielles.

        Exemple : rappel de maintenance

      • Description : indiquez la description du fonctionnement de la règle. Vous pouvez modifier cette description ultérieurement. Evitez de saisir des informations confidentielles.

        Exemple : envoie des messages à la rubrique de maintenance

    4. Dans Conditions de règle, créez un filtre pour les événements de rappel de base de données :
      • Pour Nom de service, sélectionnez Base de données.
      • Dans Type d'événement, sélectionnez Base de données Conteneur Autonomous – Rappel de maintenance.
    5. Dans Actions, sélectionnez le sujet que vous avez créé précédemment :
      1. Sélectionnez Notifications.
      2. Sélectionnez le compartiment de notifications.
      3. Sélectionnez le sujet que vous avez créé précédemment.
    6. Sélectionnez Créer une règle.
  • Créez une règle déclenchée par des rappels de maintenance et référencez cette rubrique comme destination.

    1. Créez un fichier, action.json, qui contient les éléments suivants, référençant le sujet créé précédemment.

      Exemple :

      {
        "actions": [
            {
              "actionType": "ONS",
              "description": "string",
              "isEnabled": true,
              "topicId": "<topic_OCID>"
            }
        ]
      }
    2. Ouvrez une invite de commande et exécutez la commande oci events rule create.

      Exemple :

      oci events rule create --display-name <friendly_name> --is-enabled true --condition "{\"eventType\":[\"com.oraclecloud.databaseservice.autonomous.container.database.maintenance.reminder\"]}" --compartment-id <compartment_OCID> --actions file://action.json

      Afin d'obtenir la liste complète des paramètres et des valeurs des commandes d'interface de ligne de commande, reportez-vous à Référence de commande d'interface de ligne de commande.

      Pour plus d'informations sur la création de règles à l'aide de l'interface de ligne de commande, reportez-vous à Création d'une règle d'événements.

  • Exécutez l'opération CreateRule pour créer une règle d'événement.

    Exemple :

    POST /20181201/rules
    Host: events.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    
    {
      "displayName": "Maintenance Reminder",
      "condition": "{
        \"eventType\": \"com.oraclecloud.databaseservice.autonomous.container.database.maintenance.reminder\"
        }",
      "compartmentId": "<compartment_OCID>",
      "isEnabled": true,
      "actions": {
        "actions": [
          {
            "actionType": "ONS",
            "topicId": "<topic_OCID>",
            "isEnabled": true
          }
        ]
      }
    }