Cenário C: Arquivando Tickets Jira para Lembretes

Registre automaticamente um tíquete do Jira sempre que ocorrer um evento de lembrete de manutenção. Nesse cenário, sempre que um lembrete para a próxima manutenção do banco de dados vem do Oracle Cloud Infrastructure, um ticket do Jira é criado para o engenheiro de plantão.

Esse cenário envolve a gravação de uma função no arquivo de tickets do Jira (e a criação de um segredo para armazenar credenciais do Jira), a adição dessa função e o e-mail opcional como assinaturas a um tópico e a criação de uma regra que envia mensagens para esse tópico quando ocorrem eventos de lembrete de manutenção (consulte Tipos de Evento do Autonomous Container Database ). A mensagem é enviada para as assinaturas do tópico, que inclui um endereço de e-mail de grupo além da função. A função é chamada no recebimento da mensagem.

Tudo, exceto a função, pode ser configurado no Console. Se preferir, poderá usar a CLI ou a API do Oracle Cloud Infrastructure, que permite que você mesmo execute as operações individuais.

Observação

O serviço Notifications não tem informações sobre uma função após sua chamada. Para obter detalhes, consulte as informações de diagnóstico e solução de problemas em Função Não Chamada ou Executada.

Esta imagem mostra Notificações no contexto de um cenário que usa uma função para arquivar tickets do Jira quando ocorrem eventos de lembrete.

Para obter mais informações sobre esse cenário, consulte Ticketing Automatizado do Jira usando OCI Events, Notifications e Functions e o repositório GitHub associado.

Política do Serviço IAM Obrigatória

Para usar o Oracle Cloud Infrastructure, você deve receber de um administrador o acesso de segurança em uma política . Esse acesso será necessário se você estiver usando a Console ou a API REST com um SDK, uma CLI ou outra ferramenta. Caso receba uma mensagem de que você não tem permissão ou não está autorizado, verifique com o administrador o tipo de acesso que você tem e em qual compartimento  trabalhar.

Se você for membro do grupo Administradores, já terá o acesso necessário para executar esse cenário. Caso contrário, você precisará acessar os serviços Events, Notifications e Functions. Você deve ter a permissão FN_INVOCATION na função para poder adicionar a função como uma inscrição em um tópico. Para acessar suas credenciais do Jira, a função deve estar autorizada a ler segredos. Esse cenário percorre etapas para fornecer essa autorização.

Tarefa 1: Armazenar Credenciais em um Segredo

Para obter mais informações sobre como criar segredos usando o serviço Vault, consulte Criando um Segredo em um Vault.

    1. Abra o menu de navegação, clique em Identidade e Segurança e, em seguida, clique em Vault.
    2. Em Escopo da Lista, na lista Compartimento, clique no nome do compartimento no qual você deseja criar um segredo.
    3. Na lista de vaults no compartimento, execute um dos seguintes procedimentos:

      • Clique no nome do vault no qual você deseja criar um segredo.

      • Crie um novo vault para o segredo seguindo as instruções em Para criar um novo vault e, em seguida, clique no nome do vault.

    4. Clique em Segredos e em Criar Segredo.
    5. No painel Criar Segredo, escolha um compartimento na lista Criar no Compartimento. (É possível haver segredos fora do compartimento no qual o vault reside.)
    6. Informe um Nome para identificar o segredo. Evite digitar informações confidenciais.

      Nome de exemplo: jira_auth_plain_text

    7. Informe uma Descrição breve do segredo para ajudar a identificá-lo. Evite digitar informações confidenciais.

      Exemplo de descrição: jira_auth_plain_text

    8. Escolha a chave de criptografia mestra que você deseja usar para criptografar o conteúdo do segredo enquanto ele é importado para o vault. (A chave deve pertencer ao mesmo vault.)
    9. Para Secret Type Template, selecione Plain-Text.
    10. Para Conteúdo do Segredo, informe suas credenciais do Jira no seguinte formato, com dois-pontos separando seu e-mail de log-in do token de autenticação:

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

    11. Clique em Create Secret.
    12. Anote o OCID secreto a ser usado no código de função para extrair o segredo com segurança.
  • Observação

    Especifique uma chave simétrica para criptografar o segredo durante a importação para o vault. Você não pode criptografar segredos com chaves assimétricas. Além disso, a chave deve existir no vault especificado.

    Use o comando oci vault secret create-base64 e os parâmetros necessários para criar um segredo que armazena suas credenciais do 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>

    Para obter uma lista completa dos parâmetros e valores dos comandos da CLI, consulte a Referência de Comandos da CLI.

  • Execute a operação CreateSecret para criar um segredo.

    Exemplo:

    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"
        }
    }
    Observação

    Cada região tem um ponto final exclusivo para operações de criação, atualização e lista de segredos. Este ponto final é chamado de URL do plano de controle ou ponto final de gerenciamento de segredo. Cada região também tem um ponto final exclusivo para operações relacionadas à recuperação de conteúdo de segredo. Este ponto final é conhecido como URL do plano de dados ou o ponto final de recuperação de segredo. Para pontos finais regionais, consulte a Documentação da API.

    Para obter informações sobre como usar a API e assinar solicitações, consulte a documentação da API REST e Credenciais de Segurança. Para obter informações sobre SDKs, consulte SDKs e a CLI.

Tarefa 2: Criar a Função

Esta seção fornece a amostra de código para criar sua função e abrange etapas para autorizar a função a acessar suas credenciais do Jira no segredo criado usando o serviço Vault.

Exemplo do código da função

A amostra de código a seguir é para uma função para arquivar tickets do Jira.

Adicione seu OCID de segredo na linha que inclui getSecretForOcid.

Para obter instruções sobre como criar e implantar funções, consulte Criando e Implantando Funções.

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;
}
Autorizar sua função a acessar segredos

Use um grupo dinâmico para conceder à sua função a capacidade de ler segredos. Sua função deve ter essa autorização para acessar suas credenciais do Jira, que são armazenadas no segredo criado anteriormente.

Para autorizar sua função a acessar segredos (Console)
  1. Localize e anote sua função OCID (o formato é ocid1.fnfunc.oc1.iad.exampleuniqueID).
  2. Inclua sua função em um grupo dinâmico: No grupo dinâmico relevante, especifique a seguinte regra:
    resource.id = '<function-ocid>'

    Como alternativa, você pode criar um grupo dinâmico que inclua todas as funções:

    ALL{resource.type='fnfunc', resource.compartment.id='<compartment_OCID>'}
  3. Conceda ao grupo dinâmico acesso a segredos: Adicione a seguinte política :
    allow dynamic-group <dynamic-group-name> to read secret-family in tenancy

Para autorizar sua função de acesso a outros recursos do Oracle Cloud Infrastructure, como instâncias de computação, inclua a função em um grupo dinâmico e crie uma política para conceder a esses recursos acesso ao grupo dinâmico. Para obter mais informações, consulte Acessando Outros Recursos do Oracle Cloud Infrastructure pelas Funções em Execução.

Para obter mais informações sobre grupos dinâmicos, consulte Gerenciando Grupos Dinâmicos.

Tarefa 3: Criar o Tópico

Para obter ajuda com o diagnóstico e a solução de problemas, consulte Diagnóstico e Solução de Problemas do Serviço Notifications.

    1. Abra o painel Criar Tópico: na página da lista Tópicos, selecione Criar Tópico. Se precisar de ajuda para localizar a página da lista, consulte Listando Tópicos.
    2. Para Nome, digite o seguinte: Tópico de Manutenção
    3. Clique em Criar.
  • Use o comando oci ons topic create e os parâmetros necessários para criar um tópico:

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

    Por exemplo:

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

    Para obter uma lista completa de parâmetros e valores para comandos da CLI, consulte a Referência de Linha de Comando para Notificações.

  • Execute a operação CreateTopic para criar um tópico.

    Por exemplo:

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

Tarefa 4: Criar as Assinaturas

Sua função deve ser implantada antes de criar a assinatura da função.

Para obter ajuda com o diagnóstico e a solução de problemas, consulte Diagnóstico e Solução de Problemas do Serviço Notifications.

    1. Selecione o tópico criado anteriormente (o nome do exemplo era Tópico de Manutenção): Na página da lista Tópicos, selecione o tópico com o qual você deseja trabalhar. Se precisar de ajuda para encontrar a página da lista ou o tópico, consulte Listando Tópicos.
    2. Crie a assinatura da função.
      1. Abra o painel Criar Inscrição: Na página de detalhes do tópico, clique em Criar Inscrição.
        O painel Criar Inscrição é aberto.
      2. Para Protocolo, selecione Função.
      3. Preencha os campos restantes.
        Campo Descrição
        Compartimento da Função Selecione o compartimento que contém a função.
        Aplicativo da Função Selecione o aplicativo que contém a função.
        Função Selecione a função.
      4. Clique em Criar.
        Nenhuma confirmação é necessária para novas assinaturas de função.
    3. Crie a assinatura de e-mail.
      1. Abra o painel Criar Inscrição: Na página de detalhes do tópico, clique em Criar Inscrição.
        O painel Criar Inscrição é aberto.
      2. Para Protocolo, selecione E-mail.
      3. Preencha os campos restantes.
        Campo Descrição
        E-mail Digite um endereço de e-mail.
      4. Clique em Criar.
      5. Confirmar a nova assinatura de e-mail: Abra o e-mail e navegue até o URL de confirmação.
  • Observação

    Depois de criar a assinatura de e-mail, confirme-a.

    Use o comando oci ons subscription create e os parâmetros necessários para criar cada assinatura:

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

    Exemplo de assinatura da função:

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

    Exemplo de inscrição de e-mail:

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

    Para obter uma lista completa de parâmetros e valores para comandos da CLI, consulte a Referência de Linha de Comando para Notificações.

  • Observação

    Depois de criar a assinatura de e-mail, confirme-a.

    Execute a operação CreateSubscription para criar cada assinatura.

    Exemplo de assinatura da função:

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

    Exemplo de inscrição de e-mail:

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

Tarefa 5: Criar a Regra de Eventos

  • Esta seção explica a criação da regra que envia uma mensagem ao tópico sempre que o serviço Database emite um evento para um lembrete de manutenção de banco de dados.

    1. Abra o menu de navegação e clique em Observabilidade & Gerenciamento. Em Serviço Events, clique em Regras.
    2. Escolha um Compartimento no qual você tenha permissão para trabalhar e clique em Criar Regra.

      O serviço Events compara as regras que você cria neste compartimento com mensagens de evento emitidas por recursos deste compartimento e de todos os compartimentos secundários.

    3. Informe o seguinte.
      • Nome para Exibição: Especifique um nome amigável para a regra. Você pode alterar esse nome posteriormente. Evite digitar informações confidenciais.

        Exemplo: Lembrete de Manutenção

      • Descrição: Especifique uma descrição do que a regra faz. Você pode alterar essa descrição posteriormente. Evite digitar informações confidenciais.

        Exemplo: Envia mensagens para o Tópico de Manutenção

    4. Em Condições da Regra, crie um filtro para eventos de lembrete do banco de dados:
      • Para Nome do Serviço, selecione Banco de Dados.
      • Em Tipo de evento, selecione Autonomous Container Database – Lembrete de Manutenção.
    5. Em Ações, selecione o tópico criado anteriormente:
      1. Selecione Notificações.
      2. Selecione o Compartimento de Notificações.
      3. Selecione o Tópico criado anteriormente.
    6. Clique em Criar Regra.
  • Crie uma regra que seja acionada por lembretes de manutenção e faça referência a este tópico como destino.

    1. Crie um arquivo, action.json, que contenha o seguinte, referenciando seu tópico criado anteriormente.

      Por exemplo:

      {
        "actions": [
            {
              "actionType": "ONS",
              "description": "string",
              "isEnabled": true,
              "topicId": "<topic_OCID>"
            }
        ]
      }
    2. Abra um prompt de comando e execute o comando oci events rule create.

      Por exemplo:

      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

      Para obter uma lista completa dos parâmetros e valores dos comandos da CLI, consulte a CLI Command Reference.

      Para obter mais informações sobre como criar regras usando a CLI, consulte Criando uma Regra de Eventos.

  • Execute a operação CreateRule para criar uma regra de evento.

    Por exemplo:

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