シナリオC: リマインダ用のJiraチケットの申請

このトピックでは、メンテナンス・リマインダ・イベントが発生するたびに自動Jiraチケットをファイルする方法について説明します。このシナリオでは、次回のデータベース・メンテナンスのリマインダがOracle Cloud Infrastructureから送信されるたびに、オンコール・エンジニア用のJiraチケットが作成されます。

このシナリオでは、Jiraチケットに関数を書き込み(およびJira資格証明を格納するシークレットを作成)、その関数とオプションの電子メールをサブスクリプションとしてトピックに追加し、メンテナンス・リマインダ・イベントが発生したときにそのトピックにメッセージを送信するルールを作成します(「データベース・サービス: Autonomous Container Databaseイベント・タイプ」を参照)。   メッセージはトピックのサブスクリプションに送信され、機能に加えてグループの電子メール・アドレスが含まれます。ファンクションは、メッセージの受信時に呼び出されます。

この機能以外はすべて、コンソールで設定できます。または、Oracle Cloud Infrastructure CLIまたはAPIを使用して、各操作を自分で実行することもできます。

ノート

通知サービスには、ファンクションが呼び出された後にそのファンクションに関する情報はありません。詳細は、ファンクションが呼出しまたは実行されない場合のトラブルシューティング情報を参照してください。

この画像は、リマインダ・イベントが発生したときにJiraチケットをファイルする関数を使用するシナリオのコンテキストでの通知を示しています。

このシナリオの詳細は、「OCIイベント、通知および関数 を使用した自動Jiraチケッティング」および関連するGitHubリポジトリを参照してください。

必須IAMポリシー

Oracle Cloud Infrastructureを使用するには、管理者によってポリシーでセキュリティ・アクセス権が付与されている必要があります。このアクセス権は、コンソール、あるいはSDK、CLIまたはその他のツールを使用したREST APIのいずれを使用している場合でも必要です。権限がない、または認可されていないというメッセージが表示された場合は、自分がどのタイプのアクセス権を持っているか、およびどのコンパートメントで作業するかを管理者に確認してください。

管理者グループのメンバーであれば、このシナリオを実行するために必要なアクセス権はすでに持っています。そうでない場合は、イベント通知およびファンクションにアクセスする必要があります。ファンクションをトピックのサブスクリプションとして追加するには、そのファンクションに対してFN_INVOCATION権限を持っている必要があります。Jira資格証明にアクセスするには、シークレットの読取りが認可されている必要があります。このシナリオでは、この認可を提供するステップを説明します。

タスク1: Jira資格証明のシークレットへの格納

シークレットは、コンソール、CLIまたはAPIで作成できます。このシークレットは、後でファンクションを作成するときに参照します。

コンソールの使用

Jira資格証明のシークレットを作成するには
  1. ナビゲーション・メニューを開き、「アイデンティティとセキュリティ」、「ボールト」の順にクリックします。
  2. 「リスト範囲」「コンパートメント」リストで、シークレットを作成するコンパートメントの名前をクリックします。
  3. コンパートメント内のボールトのリストから、次のいずれかを実行します。

    • シークレットを作成するボールトの名前をクリックします。

    • 新しいボールトを作成するにはの手順に従ってシークレットに新しいボールトを作成し、そのボールトの名前をクリックします。

  4. 「シークレット」をクリックし、「シークレットの作成」をクリックします。
  5. 「シークレットの作成」ダイアログ・ボックスで、「コンパートメントに作成」リストからコンパートメントを選択します。(シークレットは、ボールトが含まれるコンパートメントの外部に存在できます。)
  6. 「名前」をクリックし、シークレットを識別する名前を入力します。機密情報の入力は避けてください。

    nameの例: jira_auth_plain_text

  7. 「説明」をクリックして、シークレットを識別しやすい簡単な説明を入力します。このフィールドに機密情報を入力しないでください。

    説明の例: jira_auth_plain_text

  8. ボールトへのインポート中にシークレット・コンテンツの暗号化に使用するマスター暗号化キーを選択します。(キーは同じボールトに属する必要があります。)
  9. シークレット・タイプ・テンプレート」で、「プレーン・テキスト」を選択します。
  10. シークレット・コンテンツ」をクリックし、ログイン電子メールと認証トークンをコロンで区切ってJira資格証明を次の形式で入力します。

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

  11. シークレットの作成」をクリックします。
  12. シークレットを安全にフェッチするためにファンクション・コードで使用するシークレットOCIDを書き留めます。

Vaultサービスを使用したシークレットの作成の詳細については、「新しいシークレットを作成するには」を参照してください。

CLIの使用

CLIを使用してシークレットを作成するには

Jira資格証明を格納するシークレットを作成します:コマンド・プロンプトを開き、oci vault secret create-base64コマンドを実行します: 

oci vault secret create-base64 --compartment-id <compartment_OCID> --secret-name <secret_name> --vault-id <vault_OCID> --description <secret_description_text> --key-id <encryption_key_OCID> --secret-content-content <base64_encoded_secret_content> --secret-content-name <unique_content_name>

機密情報の入力は避けてください。

CLIを使用したシークレットの管理の詳細は、コマンド・ライン・インタフェース(CLI)の使用を参照してください。

APIの使用

APIの使用およびリクエストの署名の詳細は、REST APIおよびセキュリティ資格証明を参照してください。SDKの詳細は、ソフトウェア開発キットとコマンドライン・インタフェースを参照してください。

CreateSecret操作を使用します。

CreateSecretリクエストの例
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"
    }
}

APIを使用したシークレットの管理の詳細は、「APIの使用」を参照してください。

タスク2:ファンクションの作成

この項では、ファンクションを作成するためのコード・サンプルを示し、Vaultサービスを使用して作成されたシークレットのJira資格証明にアクセスするためのファンクションを認可するステップについて説明します。

ファンクション・コードのサンプル

次のコード・サンプルは、Jiraチケットをファイルする関数用です。

getSecretForOcidを含む行にシークレットOCIDを追加します。

ファンクションの作成およびデプロイの手順は、ファンクションの作成およびデプロイを参照してください。

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;
}
シークレットにアクセスする機能を認可します

動的グループを使用して、シークレットを読み取る権限をファンクションに付与します。以前に作成したシークレットに格納されているJira資格証明にアクセスするには、ファンクションにこの認可が必要です。

シークレットにアクセスする機能を認可するには(コンソール)
  1. ファンクションOCID (フォーマットはocid1.fnfunc.oc1.iad.exampleuniqueID)を見つけてメモします
  2. ファンクションを動的グループに含める:関連する動的グループで、次のルールを指定します。
    resource.id = '<function-ocid>'

    または、すべての関数を含む動的グループを作成することもできます。

    ALL{resource.type=’fnfunc’, resource.compartment.id=’<compartment_OCID>’}
  3. シークレットへの動的グループ・アクセス権の付与:次のポリシーを追加します。
    allow dynamic-group <dynamic-group-name> to read secret-family in tenancy

To authorize your function for access to other Oracle Cloud Infrastructure resources, such as compute instances, include the function in a dynamic group  and create a policy to grant the dynamic group access to those resources. For more information, see Accessing Other Oracle Cloud Infrastructure Resources from Running Functions.

動的グループの詳細は、動的グループの管理を参照してください。

タスク3:トピック、サブスクリプションおよびルールの作成

この項では、トピックの作成、関数およびオプションの電子メールのサブスクリプションとしての追加、データベース・サービスがデータベース・メンテナンス・リマインダのイベントを発行するたびにメッセージを送信するルールの作成について説明します。ファンクションをデプロイする必要があります。

すべてをコンソールで設定できます。または、Oracle Cloud Infrastructure CLIまたはAPIを使用して、各操作を自分で実行することもできます。

トピックおよびサブスクリプションの管理の詳細は、「トピックおよびサブスクリプションの管理」を参照してください。ルールの管理の詳細は、イベントのルールの管理を参照してください。

コンソールの使用

トピックを作成するには

この項では、サブスクリプションおよびルールに使用するトピックの作成について順を追って説明します。

  1. ナビゲーション・メニューを開き、「開発者サービス」をクリックします。「アプリケーション統合」で、「通知」をクリックします。
  2. トピック・リストの上部にある「トピックの作成」をクリックします。
  3. 「トピックの作成」ダイアログ・ボックスで、トピックを構成します。

    • 名前: 必須。トピックにわかりやすい名前を指定します。テナンシ間で一意にする必要があります。検証では大/小文字が区別されます。機密情報の入力は避けてください。

      例:メンテナンス・トピック

    • 説明: オプション。トピックの説明を入力します。機密情報の入力は避けてください。
  4. 「作成」をクリックします。

トラブルシューティングのヘルプは、通知のトラブルシューティングを参照してください。

関数サブスクリプションを作成するには

この項では、トピックへのサブスクリプションとしての関数の追加について説明します。ファンクションをデプロイする必要があります。

  1. ナビゲーション・メニューを開き、「開発者サービス」をクリックします。「アプリケーション統合」で、「通知」をクリックします。
  2. サブスクリプションを追加するトピックの名前をクリックします。

    例:メンテナンス・トピック(トピックの作成時に推奨されるトピック名を使用したことを想定)。

  3. トピックの詳細ページで、「サブスクリプションの作成」をクリックします。
  4. サブスクリプションの作成」ダイアログ・ボックスで、関数サブスクリプションを構成します: 
    ノート

    ファンクションは、デプロイする必要があります。ファンクションをトピックのサブスクリプションとして追加するには、そのファンクションに対してFN_INVOCATION権限を持っている必要があります。

    通知サービスには、ファンクションが呼び出された後にそのファンクションに関する情報はありません。詳細は、ファンクションが呼出しまたは実行されない場合のトラブルシューティング情報を参照してください。

    ファンクション・サブスクリプションの確認は必要ありません。

    • サブスクリプション・プロトコル:「ファンクション」を選択します。
    • ファンクション・コンパートメント: ファンクションを含むコンパートメントを選択します。
    • ファンクション・アプリケーション: ファンクションを含むアプリケーションを選択します。
    • ファンクション: ファンクションを選択します。
  5. 「作成」をクリックします。

    サブスクリプションが作成されました。

トラブルシューティングのヘルプは、通知のトラブルシューティングを参照してください。

電子メール・サブスクリプションを作成するには

この項では、トピックへのオプションの電子メール・サブスクリプションの追加について説明します。

  1. ナビゲーション・メニューを開き、「開発者サービス」をクリックします。「アプリケーション統合」で、「通知」をクリックします。
  2. サブスクリプションを追加するトピックの名前をクリックします。

    例:メンテナンス・トピック(トピックの作成時に推奨されるトピック名を使用したことを想定)。

  3. トピックの詳細ページで、「サブスクリプションの作成」をクリックします。
  4. サブスクリプションの作成」ダイアログ・ボックスで、電子メール・サブスクリプションを設定します:

    • プロトコル: 「電子メール」を選択します。
    • 電子メール: 電子メール・アドレスを入力します。
  5. 「作成」をクリックします。

    電子メール・サブスクリプションが作成され、指定された電子メール・アドレスにサブスクリプション確認URLが送信されます。サブスクリプションは、確認されるまで「保留中」ステータスのままです。

  6. 新しい電子メール・サブスクリプションを確認するには、電子メールを開き、確認URLに移動します。

    詳細は、サブスクリプションを確認するにはを参照してください

トラブルシューティングのヘルプは、通知のトラブルシューティングを参照してください。

ルールを作成するには:

この項では、データベース・サービスがデータベース・メンテナンス・リマインダのイベントを発行するたびにトピックにメッセージを送信するルールの作成について説明します。

  1. ナビゲーション・メニューを開き、「監視および管理」をクリックします。「イベント・サービス」で、「ルール」をクリックします。
  2. 作業の権限があるコンパートメントを選択し、「ルールの作成」をクリックします。

    イベントは、このコンパートメントに作成したルールと、このコンパートメントおよび子コンパートメントのリソースから発行されたイベント・メッセージを比較します。

  3. 次を入力します:
    • 表示名: ルールのわかりやすい名前を指定します。この名前は後で変更できます。機密情報の入力は避けてください。

      例:メンテナンス・リマインダ

    • 説明: ルールの機能に関する説明を指定します。この説明は後で変更できます。機密情報の入力は避けてください。

      例:メンテナンス・トピックへのメッセージの送信

  4. ルール条件」で、データベース・リマインダ・イベントのフィルタを作成します: 
    • サービス名」で、「データベース」を選択します。
    • イベント・タイプ」で、Autonomous Container Database –メンテナンス・リマインダを選択します。
  5. アクション」で、以前に作成したトピックを選択します:
    1. 通知」を選択します。
    2. 「通知コンパートメント」を選択します。
    3. 以前に作成したトピックを選択します。
  6. ルールの作成」をクリックします。

CLIの使用

この項では、CLIを使用したトピック、サブスクリプションおよびルールの作成手順を示します。ファンクションをデプロイする必要があります。

APIの使用およびリクエストの署名の詳細は、REST APIおよびセキュリティ資格証明を参照してください。SDKの詳細は、ソフトウェア開発キットとコマンドライン・インタフェースを参照してください。
  1. トピックの作成

    コマンド・プロンプトを開き、oci ons topic createコマンドを実行します: 

    oci ons topic create --name "Maintenance Topic" --compartment-id "<compartment-ocid>"
  2. サブスクリプションの追加

    前のステップで作成したトピックに、ファンクションOCIDおよびオプションの電子メール・アドレスを参照するサブスクリプションを追加します。

    • ファンクション・サブスクリプションの作成: コマンド・プロンプトを開き、oci ons subscription createコマンドを実行します:

      oci ons subscription create --compartment-id "<compartment-ocid>" --topic-id "<topic-ocid>" --protocol "ORACLE_FUNCTIONS" --subscription-endpoint "<function-ocid>"
    • 電子メール・サブスクリプションの作成: コマンド・プロンプトを開き、oci ons subscription createコマンドを実行します:

      oci ons subscription create --compartment-id "<compartment-ocid>" --topic-id "<topic-ocid>" --protocol "EMAIL" --subscription-endpoint "maintenance.team@example.com"
  3. ルールの作成

    メンテナンス・リマインダによってトリガーされるルールを作成し、このトピックを宛先として参照します。 

    1. 以前に作成したトピックを参照する、次の内容を含むファイルaction.jsonを作成します。
      {
        "actions": [
            {
              "actionType": "ONS",
              "description": "string",
              "isEnabled": true,
              "topicId": "<topic_OCID>"
            }
        ]
      }
    2. コマンド・プロンプトを開き、oci events rule createコマンドを実行します。 

      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

      CLIを使用したルールの作成の詳細は、ルールを作成するにはを参照してください。

トラブルシューティングのヘルプは、通知のトラブルシューティングを参照してください。

APIの使用

この項では、APIを使用したトピック、サブスクリプションおよびルールの作成手順を示します。ファンクションをデプロイする必要があります。

APIの使用およびリクエストの署名の詳細は、REST APIおよびセキュリティ資格証明を参照してください。SDKの詳細は、ソフトウェア開発キットとコマンドライン・インタフェースを参照してください。

次の操作を使用します:

  1. CreateTopic: トピックの作成。

    CreateTopicリクエストの例
    POST /20181201/topics
    Host: notification.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    {
      "name": "Maintenance Topic",
      "compartmentId": "<compartment_OCID>"
    }
  2. CreateSubscription: このトピックに、ファンクションOCIDおよびオプションの電子メール・アドレスを参照するサブスクリプションを追加します。

    CreateSubscriptionリクエストの例: ファンクション
    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>"
    }
    CreateSubscriptionリクエストの例: 電子メール
    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"
    }
  3. CreateRule:メンテナンス・リマインダによってトリガーされるルールを作成し、このトピックを宛先として参照します。

    CreateRuleリクエストの例
    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
          }
        ]
      }
    }

トラブルシューティングのヘルプは、通知のトラブルシューティングを参照してください。