ServiceNow

ServiceNow コネクタを使用すると、ServiceNow データベースに対して、挿入、削除、更新、読み取りオペレーションを実行できます。

始める前に

ServiceNow コネクタを使用する前に、次の作業を行います。

  • Google Cloud プロジェクトで次の操作を行います。
    • コネクタを構成するユーザーに roles/connectors.admin IAM ロールを付与します。
    • コネクタに使用するサービス アカウントに、次の IAM ロールを付与します。
      • roles/secretmanager.viewer
      • roles/secretmanager.secretAccessor

      サービス アカウントは特別なタイプの Google アカウントで、Google API のデータにアクセスするのに認証を受ける必要がある人間以外のユーザーを表します。サービス アカウントがない場合は、サービス アカウントを作成する必要があります。詳細については、サービス アカウントを作成するをご覧ください。

    • 次のサービスを有効にします。
      • secretmanager.googleapis.com(Secret Manager API)
      • connectors.googleapis.com(Connectors API)

      サービスを有効にする方法については、サービスを有効にするをご覧ください。

    以前にプロジェクトでこうしたサービスを有効にしていない場合は、コネクタを構成するときにそれを有効にすることを求められます。

  • ServiceNow インスタンスの次のテーブルへのアクセス権を付与します。

    • sys_db_object
    • sys_dictionary
    • sys_glide_object

    この権限は、コネクタがデータに接続するために必要です。アクセス権を付与する手順は次のとおりです。

    1. ServiceNow アプリケーションで、[System Security] > [Access Controls(ACL)] に移動します。
    2. [新規作成] を選択してアクセス制御オブジェクトを作成します。
    3. [タイプ] で [レコード] を選択します。
    4. [オペレーション] で [読み取り] を選択します。
    5. [Name] で、最初のプルダウンで [Table [sys_db_object]] を選択し、2 番目のプルダウンで [--None--] を選択します。
    6. [ロールが必要] セクションで、[新しい行を挿入] テキスト ボックスをダブルクリックし、目的のロールを見つけて選択します。
    7. [送信] をクリックして ACL オブジェクトを作成します。
    8. 作成した ACL を含むロールを認証ユーザーに割り当てます。これを行うには、[User Administration] > [Users] > [Select authenticating user] > [Roles] > [Edit]... の順で選択します。> . 次に、コレクションからロールを追加します。
  • ServiceNow インスタンスの URL、ユーザー名、パスワードを取得します。

コネクタを構成する

コネクタを構成するには、データソース(バックエンド システム)への接続を作成する必要があります。接続はデータソースに特有です。つまり、多数のデータソースがある場合は、データソースごとに別々の接続を作成する必要があります。接続を作成する手順は次のとおりです。

  1. Cloud コンソールで、[Integration Connectors] > [接続] ページに移動し、Google Cloud プロジェクトを選択または作成します。

    [接続] ページに移動

  2. [+ 新規作成] をクリックして [接続の作成] ページを開きます。
  3. [ロケーション] セクションで、接続のロケーションを選択します。
    1. リージョン: プルダウン リストからロケーションを選択します

      サポートされているすべてのリージョンの一覧については、ロケーションをご覧ください。

    2. [NEXT] をクリックします。
  4. [接続の詳細] セクションで、次の操作を行います。
    1. コネクタ: 使用可能なコネクタのプルダウン リストから [ServiceNow] を選択します。
    2. コネクタのバージョン: 使用可能なバージョンのプルダウン リストからコネクタのバージョンを選択します。
    3. [接続名] フィールドに、接続インスタンスの名前を入力します。

      接続名は次の条件を満たす必要があります。

      • 接続名には英字、数字、ハイフンを使用できます。
      • 文字は小文字のみを使用できます。
      • 接続名の先頭には英字を設定し、末尾には英字または数字を設定する必要があります。
      • 接続名は 49 文字以内で指定してください。
      • イベント サブスクリプションをサポートするコネクタの場合、接続名の先頭に接頭辞「goog」は使用できません。
    4. 必要に応じて、接続インスタンスの [説明] を入力します。
    5. 必要に応じて、Cloud Logging を有効にして、ログレベルを選択します。デフォルトのログレベルは Error に設定されています。
    6. サービス アカウント: 必要なロールを持つサービス アカウントを選択します。
    7. イベント サブスクリプションの接続を使用するには、[イベント サブスクリプションを有効にする] を選択します。これを選択すると、次のオプションが表示されます。
      • エンティティとアクションを使用したイベント サブスクリプションを有効にする: このオプションを選択すると、イベント サブスクリプションとコネクタ オペレーション(エンティティとアクション)の両方に対して接続が使用されます。
      • イベント サブスクリプションのみを有効にする: イベント サブスクリプションに対してのみ接続を使用するには、このオプションを選択します。このオプションを選択した場合は、[次へ] をクリックして、イベント サブスクリプションを構成します。
    8. システム テーブルを含める: セキュリティ データとメタデータを保存するシステム テーブルを取得するには、このオプションを選択します。これらのテーブルにアクセスできるのは、管理者ロールのユーザーのみです。
    9. テーブルをフィルタする: テーブルをカンマ区切りのリストとして指定します。このフィールドを使用すると、すべてのテーブルを取得するのではなく、接続で取得するテーブルをフィルタできます。
    10. 表示値: 接続がデータベースから表示値、実際の値、または両方の値を取得する必要があるかどうかを指定します。
    11. 注: この接続プロパティを「true」に設定すると、Servicenow API の制限により、返されるフィールドはすべて「文字列」型になります。

      • TRUE: すべてのフィールドの表示値を返します。
      • FALSE: データベースから実際の値を返します。
      • ALL: 実際の値と表示値の両方を返します。
    12. 必要に応じて、接続ノードの設定を構成します。

      • ノードの最小数: 接続ノードの最小数を入力します。
      • ノードの最大数: 接続ノードの最大数を入力します。

      ノードは、トランザクションを処理する接続の単位(またはレプリカ)です。1 つの接続でより多くのトランザクションを処理するには、より多くのノードが必要になります。逆に、より少ないトランザクションを処理するには、より少ないノードが必要になります。ノードがコネクタの料金に与える影響については、接続ノードの料金をご覧ください。値を入力しない場合は、デフォルトで最小ノード数は 2 に設定され(可用性を高めるため)、最大ノード数は 50 に設定されます。

    13. 必要に応じて、[+ ラベルを追加] をクリックして Key-Value ペアの形式でラベルを接続に追加します。
    14. [NEXT] をクリックします。
  5. [宛先] セクションに、接続するリモートホスト(バックエンド システム)の詳細を入力します。
    1. 宛先の種類: 宛先の種類を選択します。
      • リストから [ホストアドレス] を選択し、宛先のホスト名または IP アドレスを指定します。
      • バックエンド システムへのプライベート接続を確立する場合は、リストからエンドポイント アタッチメントを選択し、次にエンドポイント アタッチメントリストから必要なエンドポイント アタッチメントを選択します。

      セキュリティをさらに強化してバックエンドシステムへのパブリック接続を確立する場合は、接続用の静的アウトバウンド IP アドレスの構成を検討してから、特定の静的 IP アドレスのみを許可リストに登録するようファイアウォール ルールを構成します。

      他の宛先を入力するには、[+ 宛先を追加] をクリックします。

    2. [NEXT] をクリックします。
  6. [認証] セクションで、認証の詳細を入力します。
    1. [認証タイプ] を選択し、関連する詳細を入力します。

      Servicenow 接続でサポートされる認証タイプは次のとおりです。

      • ユーザー名とパスワードを指定する
    2. これらの認証タイプを構成する方法については、認証を構成するをご覧ください。

    3. [NEXT] をクリックします。
  7. イベント サブスクリプションを有効にしている場合は、接続作成ページに [イベント サブスクリプションの詳細] セクションが表示されます。イベント サブスクリプションの詳細の構成方法については、イベント サブスクリプションを構成するをご覧ください。
  8. Review: 接続と認証の詳細を確認します。
  9. [作成] をクリックします。

認証を構成する

使用する認証に基づいて詳細を入力します。

  • ユーザー名とパスワード
    • ユーザー名: 接続に使用する ServiceNow ユーザー名。
    • パスワード: ServiceNow ユーザー名に関連付けられたパスワードを含む Secret Manager の Secret。

イベント サブスクリプションを構成する

イベント サブスクリプションを有効にしている場合は、[イベント サブスクリプションの詳細] セクションに次の値を入力します。

  • 認証トークン:(省略可)認証トークンの Secret Manager の Secret と、[Secret のバージョン] プルダウンから対応する Secret バージョンを選択します。
  • HMAC アルゴリズム:レスポンス ペイロードを暗号化する HMAC アルゴリズムを選択します。
  • HMAC 秘密鍵: [HMAC アルゴリズム] を選択した場合、[Secret のバージョン] プルダウンから HMAC キーの Secret Manager の Secret と対応する Secret バージョンをクリックします。
  • プライベート接続を有効にする: このオプションを選択すると、プライベート接続を介して安全にイベントをリッスンできます。
  • 次のデッドレター構成を入力します。
    • デッドレター プロジェクト ID: デッドレター Pub/Sub トピックを構成した Google Cloud プロジェクト ID。
    • デッドレター トピック: 未処理イベントの詳細を書き込む Pub/Sub トピック。

接続作成後の手順

イベント サブスクリプションの構成を完了するには、ServiceNow アプリケーションで Webhook URL を登録する必要があります。したがって、接続の作成が成功したら、次の追加手順を実行します。

  1. 新しく作成した接続の接続の詳細ページに移動し、イベント サブスクリプションの Webhook URL をコピーします。
  2. ServiceNow アプリケーションにログインし、次の操作を行います。
    1. [すべて > ビジネスルール > 実行タイミング] ページで、リッスンするオペレーションを選択します。
    2. [Advanced] タブをクリックします。スクリプト エディタが開きます。
    3. コールバック URL にリクエストを送信する JavaScript を入力します。リクエストには、有効なオペレーションが発生するたびにトリガーされるペイロードが含まれています。JavaScript のサンプルは次のとおりです。

      テンプレート

      (function executeRule(current, previous /*null when async*/ ) {
      var request = new sn_ws.RESTMessageV2();
      request.setEndpoint('WEBHOOK_URL'); // here you must the listener url where you want send the event payload
      
      request.setHttpMethod('POST');
      
      var authToken = "AUTHENTICATION_TOKEN"
      request.setRequestHeader("authorization", authToken);
      request.setRequestHeader("Accept", "application/json");
      request.setRequestHeader('Content-Type', 'application/json');
      
      request.setRequestBody("{\"eventType\":\"" +
      "EVENT_TYPE" + CUSTOM_FIELDS "\"}");
      
      var data = request.getRequestBody();
      var secretKey = "SECRET_KEY";
      
      var signature = SncAuthentication.encode(data, secretKey, "ENCRYPTION_ALGORITHM");
      request.setRequestHeader("hmacauthorization",signature);
      var response = request.execute();
      
      })(current, previous);

      次のように置き換えます。

      • WEBHOOK_URL: Integration Connectors の接続の詳細ページから取得した、イベント サブスクリプションの Webhook URL。
      • AUTHENTICATION_TOKEN: 接続用に構成した認証トークンの実際のテキスト。
      • EVENT_TYPE: ServiceNow トリガーで構成したイベントタイプの実際のテキスト。
      • CUSTOM_FIELDS: リクエスト本文には常に eventType フィールドが必要です。このフィールドに加えて、要件に応じて他のフィールドを追加できます。
      • SECRET_KEY: 接続用に構成した秘密鍵の実際のテキスト。
      • ENCRYPTION_ALGORITHM: 次のいずれかの値にする必要があります。
        • HmacSHA224
        • HmacSHA256
        • HmacSHA384
        • HmacSHA512

        アルゴリズムは、接続用に構成したアルゴリズムと同じである必要があります。

      (function executeRule(current, previous /*null when async*/ ) {
      var request = new sn_ws.RESTMessageV2();
      request.setEndpoint('https://webhook.site/bb37937e-24ea-19b3-9dcd-84eca77f60eg'); // here you must the listener url where you want send the event payload
      
      request.setHttpMethod('POST');
      
      var authToken = "YWRtaW46ZkVpNypxVzhCL3VY"
      request.setRequestHeader("authorization", authToken);
      request.setRequestHeader("Accept", "application/json");
      request.setRequestHeader('Content-Type', 'application/json');
      
      request.setRequestBody("{\"caller_id\":\"" +
      current.caller_id + "\",\"eventType\":\"" +
      "service_now_event_type_1" + "\",\"company\":\"" +
      current.company + "\",\"number\":\"" +
      current.number + "\",\"description\":\"" +
      current.description + "\",\"FirstName\":\"" +
      current.u_firstname + "\",\"LastName\":\"" +
      current.u_lastname + "\",\"status\":\"" +
      current.u_status + "\",\"Element\":\"" +
      current.getElement() + "\",\"category\":\"" +
      current.category + "\",\"opened_at\":\"" +
      current.opened_at + "\",\"opened_by\":\"" +
      current.opened_by + "\",\"location\":\"" +
      current.location + "\",\"salesforceId\":\"" +
      current.u_salesforceid + "\"}"); //fields you want
      
      var data = request.getRequestBody();
      var secretKey = "YWRtaW46ZkVpNypxVzhCL3VY";
      
      // var MAC_ALG_4 = "HmacSHA384";
      var MAC_ALG_3 = "HmacSHA256";
      // var MAC_ALG_5 = "HmacSHA512";
      // var MAC_ALG_2 = "HmacSHA224";
      
      var signature = SncAuthentication.encode(data, secretKey, MAC_ALG_3);
      request.setRequestHeader("hmacauthorization",signature);
      var response = request.execute();
      
      })(current, previous);

接続構成のサンプル

このセクションでは、接続の作成時に構成するさまざまなフィールドのサンプル値を示します。

基本認証接続タイプ

フィールド名 詳細
ロケーション us-central1
コネクタ Servicenow
コネクタのバージョン 1
接続名 google-cloud-servicenow-conn
サービス アカウント Your_Project_Number@serviceaccount
表示値 True
ノードの最小数 2
ノードの最大数 50
宛先の種類 ホストアドレス
host 1 https://Your-domainname.com
ユーザー名 User_name
パスワード パスワード
シークレットのバージョン 1

接続構成のサンプル

このセクションでは、ServiceNow 接続の作成時に構成するさまざまなフィールドのサンプル値を示します。

ServiceNow ウェブ接続のタイプ

フィールド名 詳細
ロケーション us-central1
コネクタ ServiceNow
コネクタのバージョン 1
接続名 gcp-servicenow-conn
サービス アカウント SERVICE_ACCOUNT_NAME@serviceaccount
ノードの最小数 2
ノードの最大数 50
宛先の種類 ホストアドレス
host 1 https://host_name.com
ユーザー名 ユーザー名
パスワード パスワード
シークレットのバージョン 1

エンティティ、オペレーション、アクション

すべての Integration Connectors が、接続されたアプリケーションのオブジェクトを抽象化するレイヤを提供します。アプリケーションのオブジェクトには、この抽象化を通じてのみアクセスできます。抽象化は、エンティティ、オペレーション、アクションとして公開されます。

  • エンティティ: エンティティは、接続されているアプリケーションやサービスのオブジェクト、またはプロパティのコレクションと考えることができます。エンティティの定義は、コネクタによって異なります。たとえば、データベース コネクタでは、テーブルがエンティティであり、ファイル サーバー コネクタでは、フォルダがエンティティです。また、メッセージング システム コネクタでは、キューがエンティティです。

    ただし、コネクタでいずれのエンティティもサポートされていない、またはエンティティが存在しない可能性があります。その場合、Entities リストは空になります。

  • オペレーション: エンティティに対して行うことができるアクティビティです。エンティティに対して次のいずれかのオペレーションを行うことができます。

    使用可能なリストからエンティティを選択すると、そのエンティティで使用可能なオペレーションのリストが生成されます。オペレーションの詳細については、コネクタタスクのエンティティ オペレーションをご覧ください。ただし、コネクタがいずれかのエンティティ オペレーションをサポートしていない場合、サポートされていないオペレーションは Operations リストに含まれません。

  • アクション: コネクタ インターフェースを介して統合で使用できる主要な関数の一つです。アクションを使用すると、1 つまたは複数のエンティティに対して変更を加えることができます。また、使用できるアクションはコネクタごとに異なります。通常、アクションには入力パラメータと出力パラメータがあります。ただし、コネクタがどのアクションもサポートしていない可能性があります。その場合は、Actions リストが空になります。

操作

このセクションでは、Servicenow 接続でサポートされているすべてのアクションを一覧表示します。

UploadAttachment アクション

このアクションでは、指定したレコードにファイルを添付ファイルとしてアップロードします。

UploadAttachment アクションの入力パラメータ

パラメータ名 データ型 必須 説明
コンテンツ 文字列 × ファイルとしてアップロードする文字列コンテンツ。
ContentBytes 文字列 × ファイルとしてアップロードするバイト コンテンツ。
HasBytes ブール値 × コンテンツをバイトとしてアップロードするかどうか。
TableName 文字列 × ファイルを添付するテーブルの名前。
TableSysId 文字列 × ファイルを添付する TableName で指定されたテーブル内のレコードの Sys_id。

UploadAttachment アクションの出力パラメータ

このアクションは、アップロードされたエンティティからパラメータのセットを返します。

UploadAttachment アクションの構成例については、をご覧ください。

DownloadAttachment アクション

この操作では、特定のレコードから添付ファイルをダウンロードします。

DownloadAttachment アクションの入力パラメータ

パラメータ名 データ型 必須 説明
SysId 文字列 はい 添付ファイルの Sys_id。
HasBytes ブール値 × コンテンツをバイトとしてダウンロードするかどうか。

DownloadAttachment アクションの出力パラメータ

このアクションは、ダウンロードが成功したかどうかを Success パラメータで返します。成功した場合は、DownloadAttachment の Content を出力します。

DownloadAttachment アクションの構成例については、をご覧ください。

このセクションでは、このコネクタでエンティティ オペレーションとアクションの一部を実行する方法について説明します。

例 - インシデントの添付ファイルをアップロードする

  1. [Configure connector task] ダイアログで、[Actions] をクリックします。
  2. [UploadAttachment] アクションを選択してから、[完了] をクリックします。
  3. [コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
    {
      "Content": "File is uploaded",
      "TableName": "Incident",
      "TableSysId": "018f4057473ae5104593a6b5316d4357"
    }
  4. この例では、ペイロードの Content 値を添付ファイルとしてアップロードし、アップロードされたエンティティのパラメータ セットを返します。アクションが成功すると、UploadAttachment タスクの connectorOutputPayload レスポンス パラメータの値は次のようになります。

    {
    "SysId": "a667f5d1939be110ff87352d6cba10fc",
    "FileName": "7043426257788756581.connector.txt",
    "TableSysId": "018f4057473ae5104593a6b5316d4357",
    "TableName": "Incident",
    "DownloadLink": "https://gcp.service-now.com/api/now/v1/attachment/a667f5d1939be110ff87352d6cba10fc/file",
    "ContentType": "text/plain",
    "SizeBytes": "16",
    "ChunkSizeBytes": "700000",
    "Compressed": "true",
    "SizeCompressed": "36",
    "SysTags": "",
    "ImageHeight": "",
    "ImageWidth": "",
    "AverageImageColor": "",
    "SysModCount": "0",
    "Hash": "807e96c2942c41ad699d004a9d6a74595c84fab09111d479b6bbe013d5debff6",
    "State": "pending",
    "SysUpdatedBy": "gcp2",
    "SysUpdatedOn": "2023-06-07 07:23:34",
    "SysCreatedBy": "gcp2",
    "SysCreatedOn": "2023-06-07 07:23:34",
    "encryption_context": ""
    }

例 - インシデントの添付ファイルをダウンロードする

  1. [Configure connector task] ダイアログで、[Actions] をクリックします。
  2. [DownloadAttachment] アクションを選択してから、[完了] をクリックします。
  3. [コネクタ] タスクの [タスク入力] セクションで、connectorInputPayload をクリックし、Default Valueフィールドに次のような値を入力します。
    {
      "SysId": "440c3995471fe1104593a6b5316d4384"
    }
  4. この例では、Success パラメータを使用してダウンロードが True か False かを返します。True の場合、DownloadAttachment の Content を出力します。アクションが成功すると、DownloadAttachment タスクの connectorOutputPayload レスポンス パラメータの値は次のようになります。

    [{
    "Success": "True"
    },
    {
    "Content": " A Simple Text File \r\n\r\n\r\n This is a small demonstration .txt file - \r\n just for use in the Virtual Mechanics tutorials. More text. And more \r\n text. And more text. And more text. And more text. \r\n And more text. And more text. And more text. And more text. And more \r\n text. And more text. Boring, zzzzz. And more text. And more text. And \r\n more text. And more text. And more text. And more text. And more text. \r\n And more text. And more text. \r\n And more text. And more text. And more text. And more text. And more \r\n text. And more text. And more text. Even more. Continued on page 2 ...\r\n Simple PDF File 2 \r\n ...continued from page 1. Yet more text. And more text. And more text. \r\n And more text. And more text. And more text. And more text. And more \r\n text. Oh, how boring typing this stuff. But not as boring as watching \r\n paint dry. And more text. And more text. And more text. And more text. \r\n Boring. More, a little more text. The end, and just as well. "
    }]

エンティティ オペレーションの例

このセクションでは、このコネクタでエンティティ オペレーションの一部を実行する方法について説明します。

例 - エンティティ「Incident」の単一レコードを取得する

  1. [Configure connector task] ダイアログで、[Entities] をクリックします。
  2. Entity リストから Incident を選択します。
  3. [GET] オペレーションを選択してから、[完了] をクリックします。
  4. エンティティ ID を「0c5f3cece1b12010f877971dea0b1449」に設定します。これは渡されるキーです。エンティティ ID を設定するには、[データ マッピング] の [データ マッパー] セクションで [データ マッピング エディタを開く] をクリックし、[入力値] フィールドに "0c5f3cece1b12010f877971dea0b1449" を入力して、EntityId をローカル変数として選択します。

システムの上限

ServiceNow コネクタは、ノードごとに 1 秒あたり最大 10 件のトランザクションを処理し、この上限を超えるトランザクションをthrottlesできます。デフォルトでは、Integration Connectors は、接続に 2 つのノードを割り当てます(可用性を高めるため)。

Integration Connectors に適用される上限の詳細については、上限をご覧ください。

Terraform を使用して接続を作成する

Terraform リソースを使用して、新しい接続を作成できます。

Terraform 構成を適用または削除する方法については、基本的な Terraform コマンドをご覧ください。

接続作成用の Terraform テンプレートのサンプルを表示するには、サンプル テンプレートをご覧ください。

Terraform を使用してこの接続を作成する場合は、Terraform 構成ファイルで次の変数を設定する必要があります。

パラメータ名 データ型 必須 説明
proxy_enabled BOOLEAN False 接続用のプロキシ サーバーを構成するには、このチェックボックスをオンにします。
proxy_auth_scheme ENUM False ProxyServer プロキシへの認証に使用する認証タイプです。サポートされている値は、BASIC、DIGEST、NONE です。
proxy_user STRING False ProxyServer プロキシへの認証に使用されるユーザー名です。
proxy_password SECRET False ProxyServer プロキシの認証に使用されるパスワード。
proxy_ssltype ENUM False ProxyServer プロキシへの接続時に使用する SSL のタイプです。サポートされている値は AUTO、ALWAYS、NEVER、TUNNEL です。
include_system_tables BOOLEAN False システム テーブルを公開するかどうかを制御します。
filter_tables STRING False 必要なテーブルをカンマ区切りのリストで指定します。

統合で Servicenow 接続を使用する

接続を作成すると、Apigee Integration と Application Integration の両方で使用できるようになります。この接続は、コネクタタスクを介して統合で使用できます。

  • Apigee Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。
  • Application Integration で Connectors タスクを作成して使用する方法については、Connectors タスクをご覧ください。

Google Cloud コミュニティの助けを借りる

Google Cloud コミュニティの Cloud フォーラムで質問を投稿したり、このコネクタについてディスカッションしたりできます。

次のステップ