Scénario C : Dépôt de billets 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, lorsqu'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.

This scenario involves writing a function to file Jira tickets (and creating a secret to store Jira credentials), adding that function and optional email as subscriptions  to a topic , and creating a rule that sends messages to that topic when maintenance reminder events occur (see Autonomous Container Database Event Types ). Le message est diffusé aux abonnements du sujet, qui comprend une adresse de courriel 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. Vous pouvez également utiliser l'interface de ligne de commande ou l'API d'Oracle Cloud Infrastructure, qui vous permettent d'exécuter vous-même les opérations individuelles.

Note

Le service d'avis n'a aucune information sur une fonction une fois celle-ci appelée. Pour plus de détails, consultez les informations sur le dépannage sous Fonction non appelée ou non exécutée.

Cette image présente les 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, voir Ticketing Jira automatisé à l'aide d'événements, d'avis et de fonctions OCI et le référentiel GitHub associé.

Politique GIA requise

Pour utiliser Oracle Cloud Infrastructure, un administrateur doit être membre d'un groupe auquel l'accès de sécurité est accordé dans une politique par un administrateur de location. Cet accès est requis que vous utilisiez la console ou l'API REST avec une trousse SDK, l'interface de ligne de commande ou un autre outil. Si vous obtenez un message indiquant que vous ne disposez pas de l'autorisation requise, vérifiez auprès de l'administrateur de la location quel type d'accès vous avez et dans quel compartiment votre accès fonctionne.

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 avoir accès aux services d'événements, d'avis et de fonctions. Vous devez avoir l'autorisation FN_INVOCATION pour pouvoir ajouter la fonction en tant qu'abonnement à un sujet. Pour accéder à vos données d'identification Jira, la fonction doit être autorisée à lire les clés secrètes. Ce scénario passe en revue les étapes pour fournir cette autorisation.

Tâche 1 : Stocker les données d'identification dans une clé secrète

Pour plus d'informations sur la création de clés secrètes à l'aide du service de chambre forte, voir Création d'une clé secrète dans une chambre forte.

    1. Ouvrez le menu de navigation , sélectionnez Identité et sécurité, puis Chambre forte.
    2. Sous Portée de la liste, dans la liste compartiment, sélectionnez le nom du compartiment dans lequel vous souhaitez créer une clé secrète.
    3. Dans la liste des chambres fortes du compartiment, effectuez l'une des opérations suivantes :

      • Sélectionnez le nom de la chambre forte dans laquelle vous voulez créer une clé secrète.

      • Créez une chambre forte pour la clé secrète en suivant les instructions sous Pour créer une chambre forte, puis sélectionnez le nom de la chambre forte.

    4. Sélectionnez Clés secrètes, puis Créer une clé secrète.
    5. Dans le panneau Créer une clé secrète, sélectionnez un compartiment dans la liste Créer dans le compartiment. (Des clés secrètes peuvent exister hors du compartiment dans lequel se trouve la chambre forte.)
    6. Entrez un nom pour identifier la clé secrète. Évitez d'entrer des informations confidentielles.

      Exemple de nom : jira_auth_plain_text

    7. Entrez une brève description de la clé secrète pour vous aider à l'identifier. Évitez d'entrer des informations confidentielles.

      Exemple de description : jira_auth_plain_text

    8. Choisissez la clé de chiffrement principale à utiliser pour chiffrer le contenu de la clé secrète lors de son importation dans la chambre forte. (La clé doit appartenir à la même chambre forte.)
    9. Pour Modèle de type de clé secrète, sélectionnez Texte brut.
    10. Pour Contenu de la clé secrète, entrez vos données d'identification Jira dans le format suivant, avec un deux-points séparant votre courriel de connexion de votre jeton d'authentification :

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

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

    Vous devez spécifier une clé symétrique pour chiffrer la clé secrète lors de l'importation dans la chambre forte. Vous ne pouvez pas chiffrer des clés secrètes avec des clés asymétriques. En outre, la clé doit exister dans la chambre forte que vous spécifiez.

    Utilisez la commande oci vault secret create-base64 et les paramètres requis pour créer une clé secrète stockant vos données 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 la liste complète des paramètres et des valeurs pour les commandes de l'interface de ligne de commande, voir .

  • 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"
        }
    }
    Note

    Chaque région comporte un point d'extrémité unique pour les opérations de création, de mise à jour et d'affichage des opérations liées aux clés secrètes. Ce point d'extrémité est appelé URL de point de contrôle ou point d'extrémité de gestion des clés secrètes. Chaque région dispose également d'un point d'extrémité unique pour les opérations liées à l'extraction du contenu des clés secrètes. Ce point d'extrémité est appelé URL de plan de données ou point d'extrémité d'extraction de clé secrète. Pour connaître les points d'extrémité régionaux, consultez la documentation sur les API.

    Pour plus d'informations sur l'utilisation de l'API et sur les demandes de signature, voir la documentation de l'API REST et Données d'identification de sécurité. Pour plus d'informations sur les trousses SDK, voir Trousses SDK et interface de ligne de commande.

Tâche 2 : Créer la fonction

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

Exemple de code de fonction

L'exemple de code suivant concerne une fonction permettant de classer des tickets Jira.

Ajoutez votre 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, voir 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 permettre à votre fonction de lire les clés secrètes. Votre fonction doit disposer de cette autorisation pour accéder à vos données 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 votre fonction (format : ocid1.fnfunc.oc1.iad.exampleuniqueID).
  2. Incluez votre fonction dans un groupe dynamique : Dans le groupe dynamique pertinent, spécifiez la règle suivante :
    resource.id = '<function-ocid>'

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

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

Pour autoriser votre fonction à accéder aux autres ressources Oracle Cloud Infrastructure, telles que les instances de calcul, incluez-la dans un groupe dynamique et créez une politique accordant à ce groupe l'accès aux ressources. Pour plus d'informations, voir Accès à d'autres ressources Oracle Cloud Infrastructure à partir de fonctions en cours d'exécution.

Pour plus d'informations sur les groupes dynamiques, voir Gestion des groupes dynamiques.

Tâche 3 : Créer le sujet

Pour obtenir de l'aide concernant le dépannage, voir Dépannage des avis.

    1. Ouvrez le panneau Créer un sujet : Dans la page de liste Sujets, sélectionnez Créer un sujet. Si vous avez besoin d'aide pour trouver la page de liste, voir Liste des sujets.
    2. Pour Nom, entrez 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>"

    Pour la liste complète des paramètres et valeurs des commandes de l'interface de ligne de commande, voir Référence de ligne de commande pour les avis.

  • 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

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

Pour obtenir de l'aide concernant le dépannage, voir Dépannage des avis.

    1. Sélectionnez le sujet que vous avez créé précédemment (par exemple, le nom était Sujet de maintenance) : Dans la page de liste Sujets, sélectionnez le sujet avec lequel vous voulez travailler. Si vous avez besoin d'aide pour trouver la page de liste ou le sujet, voir Liste des sujets.
    2. Créez l'abonnement à la fonction.
      1. Ouvrez le panneau Créer un abonnement : dans la page de détails du sujet, sélectionnez Créer un abonnement.
        Le panneau Créer un abonnement s'ouvre.
      2. Pour Protocole, sélectionnez Fonction.
      3. Remplissez les champs restants.
        Champ Description
        Compartiment de la 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 de courriel.
      1. Ouvrez le panneau Créer un abonnement : dans la page de détails du sujet, sélectionnez Créer un abonnement.
        Le panneau Créer un abonnement s'ouvre.
      2. Pour Protocole, sélectionnez Courriel.
      3. Remplissez les champs restants.
        Champ Description
        Courriel Entrez une adresse de courriel.
      4. Sélectionnez Créer.
      5. Confirmer le nouvel abonnement à un courriel : Ouvrez le courriel et naviguez jusqu'à l'URL de confirmation.
  • Note

    Après avoir créé l'abonnement au courriel, 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 à une fonction :

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

    Exemple d'abonnement par courriel :

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

    Pour la liste complète des paramètres et valeurs des commandes de l'interface de ligne de commande, voir Référence de ligne de commande pour les avis.

  • Note

    Après avoir créé l'abonnement au courriel, confirmez-le.

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

    Exemple d'abonnement à une 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 par courriel :

    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 au sujet chaque fois que le service de base de données émet un événement pour un rappel de maintenance de base de données.

    1. Ouvrez le menu de navigation et sélectionnez Observabilité et gestion. Sous Service d'événements, sélectionnez Règles.
    2. Sélectionnez un compartiment que vous êtes autorisé à utiliser, puis sélectionnez Créer une règle.

      Les événements comparent les règles que vous créez dans ce compartiment pour les messages d'événement émis à partir des ressources du compartiment et des compartiments enfants.

    3. Entrez les informations suivantes .
      • Nom d'affichage : Spécifiez un nom convivial pour la règle. Vous pouvez modifier cette valeur plus tard. Évitez d'entrer des informations confidentielles.

        Exemple : Rappel de maintenance

      • Description : Entrez une description de la règle. Vous pouvez modifier cette valeur plus tard. Évitez d'entrer des informations confidentielles.

        Exemple : Envoie des messages à un sujet 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 du service, sélectionnez Base de données.
      • Dans Type d'événement, sélectionnez Base de données conteneur autonome - Rappel de maintenance.
    5. Dans Actions, sélectionnez le sujet que vous avez créé précédemment :
      1. Sélectionnez Avis.
      2. Sélectionnez le compartiment des avis.
      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érence cette rubrique en tant que destination.

    1. Créez un fichier, action.json, qui contient les éléments suivants, référençant votre 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

      Pour la liste complète des paramètres et des valeurs pour les commandes de l'interface de ligne de commande, voir Informations de référence sur les commandes de l'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, voir Création d'une règle d'événement.

  • 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
          }
        ]
      }
    }