Cmdlets for ServiceNow

Build 24.0.9062

接続の確立

CData Cmdlets ユーザーは、データモジュールをインストールし、接続プロパティを設定してスクリプトを開始できます。このセクションでは、CSV インポートおよびエクスポートcmdlet などのネイティブPowerShell cmdlet でServiceNow Cmdlets を使用する例を示します。

インストールおよび接続

PSGet がある場合は、PowerShell Gallery から次のコマンドを使ってcmdlet をインストールできます。CData サイトからセットアップを取得することもできます。 

Install-Module ServiceNowCmdlets

プロファイルに以下を追加すると、次のセッションでcmdlet がロードされます。 

Import-Module ServiceNowCmdlets;

Connect-ServiceNow cmdlet を使って、別のcmdlet に渡すことができる接続オブジェクトを作成します。 

$conn = Connect-ServiceNow -OAuthClientId "MyClientId" -OAuthClientSecret "MyClientSecret" -Password "MyPassword" -User "MyUser" -Url "https://MyInstance12345.service-now.com/"

ServiceNow への接続

認証ユーザーがServiceNow に接続する場合、以下のようなリストのメタデータにアクセスするには、少なくともRead パーミッションが必要です。

  • sys_db_object（すべてのデータに必要）
  • sys_glide_object（特定のServiceNow テーブルメタデータに必要）
  • sys_dictionary（ServiceNow スキーマ情報を取得するために必要）

これを有効にするには、以下のようにユーザーのロールを昇格させる必要があります。

  1. Admin コンソールでuser menu -> Elevate Roles に移動します。
  2. check the security _admin box で、OK をクリックします。

ユーザーはまた、テーブルにアクセスするために少なくとも行レベルの権限が必要です。また、すべての接続でUrl プロパティが必要です。

READ sys_db_object

行レベルとフィールドレベルの権限が必要です。sys_db_object へのアクセスを有効化します。

  1. システムセキュリティ -> アクセス制御（ACL）に移動します。
  2. 新しいアクセス制御（ACL）オブジェクトを作成するには、New を選択します。
    • タイプには、レコードを選択します。
    • 操作には、読み取りを選択します。
    • 名前には、最初のドロップダウンでテーブル[sys_db_object] を、2番目のドロップダウンで--None-- を選択します。
    • 必要なロールセクションで、Insert a new row... テキストボックスをダブルクリックします。希望するロールを検索して、選択します。
  3. 送信をクリックして、ACL オブジェクトを作成します。
  4. ユーザー管理 -> ユーザー -> Select authenticating user -> ロール -> 編集... に移動します。
  5. 開いたページで、新しいACL に必要なロールを追加します。
  6. 新しいACL に必要であるとして指定したロールを、認証ユーザーに割り当てます。

READ sys_glide_object

行レベルとフィールドレベルの権限が必要です。sys_glide_object へのアクセスを有効化します。

  1. システムセキュリティ -> アクセス制御（ACL）に移動します。
  2. 新しいアクセス制御（ACL）オブジェクトを作成するには、New を選択します。
    • タイプには、レコードを選択します。
    • 操作には、読み取りを選択します。
    • 名前には、最初のドロップダウンでフィールドクラス[sys_glide_object] を、2番目のドロップダウンで--None-- を選択します。
    • 必要なロールセクションで、Insert a new row... テキストボックスをダブルクリックします。希望するロールを検索して、選択します。
  3. 送信をクリックして、ACL オブジェクトを作成します。
  4. ユーザー管理 -> ユーザー -> Select authenticating user -> ロール -> 編集... に移動します。
  5. 開いたページで、新しいACL に必要なロールを追加します。
  6. 新しいACL に必要であるとして指定したロールを、認証ユーザーに割り当てます。

READ sys_dictionary

sys_dictionary へのアクセスを有効化します。

  1. ユーザー管理 -> ユーザー -> Select authenticating user -> ロール -> 編集... に移動します。
  2. コレクションから"personalize_dictionary" ロールを追加します。

ServiceNow への認証

ServiceNow は、Basic 認証、OAuth 標準による認証、PASSWORD グラント種別による認証、SSO プロバイダーによる認証をサポートします。

Basic

Basic 認証を使用するには、ServiceNow User およびPassword を提供する必要があります。

次の接続プロパティを設定して、接続してください。

  1. AuthScheme： BASIC。
  2. User：BASIC ユーザー。
  3. Password：BASIC ユーザーのパスワード。
  4. Url：ServiceNow インスタンスのサイトのベースURL。例： https://MyInstance12345.service-now.com/。

OAuth

ServiceNow は、ユーザーがSSO 経由でログインしていない場合でBasic 認証も使用していない場合、すべての状況でOAuth 認証をサポートします。この認証を有効にするには、すべてのOAuth フローでAuthScheme をOAuth に設定し、カスタムOAuth アプリケーションを作成する必要があります。これらのOAuth 値の他に、Url、User およびPassword の指定も必要です。

以下のサブセクションでは、3つの一般的な認証フローでのServiceNow への認証について詳しく説明します。カスタムOAuth アプリケーションの作成については、カスタムOAuth アプリケーションの作成 を参照してください。

ServiceNow で利用可能な接続文字列プロパティの全リストは、Connection を参照してください。

デスクトップアプリケーション

カスタムOAuth アプリケーションの資格情報を使用して認証するには、OAuth アクセストークンを取得し、更新する必要があります。これらを設定すると、接続の準備が整います。

OAuth アクセストークンの取得およびリフレッシュ：

  • InitiateOAuth： GETANDREFRESH。OAuthAccessToken を自動的に取得およびリフレッシュするために使用します。
  • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
  • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。
  • CallbackURL：アプリケーションの登録時に定義されたリダイレクトURI。

接続すると、本製品 はデフォルトブラウザでServiceNow のOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。

アクセストークンの期限が切れたときは、本製品 は自動でアクセストークンをリフレッシュします。

OAuth アクセストークンの自動リフレッシュ：

本製品 がOAuth アクセストークンを自動的にリフレッシュするようにするには、次のように設定します。

  1. はじめてデータに接続する前に、次の接続プロパティを設定します。
    • InitiateOAuth： REFRESH。
    • OAuthClientId：アプリケーション設定のクライアントId。
    • OAuthClientSecret：アプリケーション設定のクライアントシークレット。
    • OAuthAccessToken：GetOAuthAccessToken によって返されたアクセストークン。
    • OAuthSettingsLocation：本製品 がOAuth 値を保存する場所のパス。これは接続間で維持されます。
  2. その後のデータ接続では、以下を設定します。
    • InitiateOAuth
    • OAuthSettingsLocation

OAuth アクセストークンの手動リフレッシュ：

OAuth アクセストークンを手動でリフレッシュするために必要な唯一の値は、OAuth リフレッシュトークンです。

  1. ExpiresIn 期間（GetOAuthAccessToken が返す）が経過した後にOAuthAccessToken を手動でリフレッシュするには、RefreshOAuthAccessToken ストアドプロシージャを呼び出します。
  2. 次の接続プロパティを設定します。

    • OAuthClientId：アプリケーション設定のクライアントId。
    • OAuthClientSecret：アプリケーション設定のクライアントシークレット。

  3. RefreshOAuthAccessToken を呼び出し、OAuthRefreshToken にGetOAuthAccessToken によって返されたOAuth リフレッシュトークンを設定します。
  4. 新しいトークンが取得できたら、OAuthAccessToken プロパティにRefreshOAuthAccessToken によって返された値を設定します。これで新規接続が開かれます。

OAuth リフレッシュトークンを保存し、OAuth アクセストークンの有効期限が切れた後に手動でリフレッシュできるようにします。

ヘッドレスマシン

ヘッドレスマシンに置かれているリソースにログインする必要がある場合は、インターネットブラウザに対応した別の端末で認証する必要があります。 以下のいずれかの方法で行います。

  • オプション1：OAuthVerifier 値を取得します。
  • オプション2：インターネットブラウザに対応したマシンに本製品 をインストールし、通常のブラウザベースのフローで認証した後でOAuth 認証値を転送します。

オプション1またはオプション2を実行後、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするようにドライバーを設定します。

オプション1：Verifier code を取得および交換

Verifier code を取得するには、OAuth Authorization URL で認証する必要があります。以下の手順に従います。

  1. インターネットブラウザに対応したマシンから認証してOAuthVerifier 接続プロパティを取得します。

    次のプロパティを設定します。

    • InitiateOAuth： OFF。
    • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
    • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。

  2. GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャは、カスタムOAuth アプリケーションが登録されたときに構築されたCallbackURL を返します。 （カスタムOAuth アプリケーションの作成 を参照してください。）

    このURL をコピーして、新しいブラウザのタブに貼り付けます。

  3. ログインして、本製品 にアクセス許可を与えます。OAuth アプリケーションは、code というパラメータを付加したリダイレクトURI にリダイレクトします。このパラメータの値を控えておきます。OAuthVerifier 接続プロパティを設定するために、後で必要になります。

  4. OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換します。ヘッドレスマシンでは、次の接続プロパティを設定してOAuth 認証値を取得します。

    • InitiateOAuth： REFRESH。
    • OAuthVerifier：控えておいたverifier code（リダイレクトURI のcode パラメータの値）。
    • OAuthSettingsLocation：暗号化されたOAuth 認証値を指定されたファイルに永続化。
    • OAuthClientId：カスタムOAuth アプリケーション設定のクライアントId。
    • OAuthClientSecret：カスタムOAuth アプリケーション設定のクライアントシークレット。

  5. 接続をテストしてOAuth 設定ファイルを生成します。

  6. 次のプロパティを再設定して、接続してください。

    • InitiateOAuth： REFRESH。
    • OAuthSettingsLocation：暗号化されたOAuth 認証値を含むファイル。アクセストークンの自動リフレッシュを有効にするには、このファイルが本製品 に読み書きのアクセス許可を与えることを確認してください。
    • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId。
    • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレット。

オプション2：OAuth 設定を転送

ヘッドレスマシンでの接続に先立ち、インターネットブラウザに対応したデバイスでドライバーとの接続をインストールし、作成する必要があります。上述の「デスクトップアプリケーション」の説明に従って、接続プロパティを設定します。

「デスクトップアプリケーション」の手順が完了すると、生成された認証値は、OAuthSettingsLocation で指定されたパスに暗号化されて書き込まれます。デフォルトのファイル名はOAuthSettings.txt です。

接続をテストしてOAuth 設定ファイルを生成し、OAuth 設定ファイルをヘッドレスマシンにコピーします。

ヘッドレスマシンでデータに接続するには、次の接続プロパティを設定します。

  • InitiateOAuth： REFRESH
  • OAuthSettingsLocation：ブラウザでマシンからコピーしたOAuth 設定ファイルへのパス。アクセストークンの自動リフレッシュを有効にするために、このファイルが本製品 に読み書きのアクセス許可を与えることを確認してください。
  • OAuthClientId：カスタムOAuth アプリケーションの登録時に割り当てられたクライアントId。
  • OAuthClientSecret：カスタムOAuth アプリケーションの登録時に割り当てられたクライアントシークレット。

パスワードグラント種別

ユーザーとアプリケーションの間に信頼関係がある場合、ユーザーはPASSWORD グラントタイプを使用して、デスクトップまたはWeb から認証できます。

PASSWORD グラントタイプを介して認証するには、次のプロパティを設定します。

  • AuthScheme：OAuthPassword。
  • InitiateOAuth：GETANDREFRESH。この設定により、OAuth 交換や、手動でのOAuthAccessToken 接続プロパティの設定の繰り返しを避けられます。
  • OAuthClientId：clientId。
  • OAuthClientSecret：clientSecret。
  • Username：ユーザーのユーザーネーム。
  • Password：ユーザーのパスワード。
  • Url：ServiceNow インスタンスのサイトのベースURL。
接続すると、本製品 はOAuth 処理を完了します。

  1. CallbackURL からアクセストークンを取得します。
  2. 古いトークンの期限が切れたときは、新しいアクセストークンを取得します。
  3. OAuthSettingsLocation に地理位置情報とともにOAuth 値を保存し、接続間で永続化されるようにします。

シングルサインオンID プロバイダー

ServiceNow は、ADFS、Okta、OneLogin、PingFederate によるシングルサインオン（SSO）認証をサポートします。

ADFS

ADFS に接続するには、AuthScheme をADFS に設定し、次のプロパティを設定します。

  • User：ADFS ユーザー。
  • Password：ADFS ユーザーのパスワード。
  • SSOLoginURL：SSO プロバイダーのログインURL。

ADFS への認証を行うには、次のSSOProperties を設定します。

  • RelyingParty：ADFS サーバーのRelying Party Identifier の値。

接続文字列の例： 

AuthScheme=ADFS;User=username;Password=password;SSOLoginURL='https://sts.company.com';SSOProperties='RelyingParty=https://saml.service-now.com';Url=https://MyInstance12345.service-now.com/;

ADFS 統合

ADFS 統合フローでは、現在ログインしているWindows ユーザーの資格情報で接続します。 ADFS 統合フローを使用するには、User およびPassword を指定せず、それ以外の設定は上記のADFS ガイドと同じ手順を実行してください。

Okta

Okta に接続するには、AuthScheme をOkta に設定し、次のプロパティを設定します。

  • User：Okta ユーザー。
  • Password：Okta ユーザーのパスワード。
  • SSOLoginURL：SSO プロバイダーのログインURL。

Okta クライアントリクエストコンテキストをオーバーライドする信頼されたアプリケーションまたはプロキシを使用する場合、またはMFA を設定している場合は、Okta を使用して認証するためにSSOProperties を組み合わせて使用する必要があります。必要に応じて、以下のいずれかを設定します。

  • APIToken：Okta クライアントリクエストコンテキストをオーバーライドする、信頼されたアプリケーションまたはプロキシ経由でユーザーを認証する場合、これを顧客がOkta 組織で作成したAPI Token に設定します。
  • MFAType：MFA フローを設定した場合、次の対応するタイプのいずれかに設定します：OktaVerify、Email、またはSMS。
  • MFAPassCode：MFA フローを設定した場合は、有効なパスコードに設定します。
    これを空欄または無効な値に設定した場合、本製品 はユーザーのデバイスまたはE メールにワンタイムパスワードチャレンジを発行します。パスコードを受信後、取得したワンタイムパスワードをMFAPassCode 接続プロパティに設定する接続を再度開きます。
  • MFARememberDevice：デフォルトはTrue です。Okta は、MFA が必要な場合にデバイスを記憶させることをサポートします。設定された認証ポリシーに従ってデバイスの記憶が許可されている場合、本製品 はMFA 認証の有効期間を延長するデバイストークンを送信します。MFA を記憶させない場合は、この 変数をFalse に設定してください。

接続文字列の例： 

AuthScheme=Okta;SSOLoginURL='https://example.okta.com/home/appType/0bg4ivz6cJRZgCz5d6/46';User=oktaUserName;Password=oktaPassword;Url=https://MyInstance12345.service-now.com/;

OneLogin

OneLogin に接続するには、AuthScheme をOneLogin に設定し、次のプロパティを設定します。

  • User：OneLogin ユーザー。
  • Password：OneLogin ユーザーのパスワード。

OneLogin への認証を行うには、次のSSOProperties を設定します。

  • OAuthClientId：Developers -> API Credentials -> Credential -> ClientId を選択して取得できるOAuthClientId。
  • OAuthClientSecret：Developers -> API Credentials -> Credential -> ClientSecret を選択して取得できるOAuthClientSecret。
  • Subdomain：SSO アプリケーションにアクセスするOneLogin ユーザーのサブドメイン。例えば、 OneLogin URL がsplinkly.onelogin.com の場合、splinkly がサブドメインの値です。
  • AppId：SSO アプリケーションのId。
  • リージョン（オプション）：OneLogin アカウントで使用しているリージョン。有効な値はUS（デフォルト）またはEU です。

次の例の接続文字列はOneLogin への接続にAPI Key を使います： 

AuthScheme=OneLogin;User=OneLoginUserName;Password=OneLoginPassword;SSOProperties='OAuthClientID=3fc8394584f153ce3b7924d9cd4f686443a52b;OAuthClientSecret=ca9257fd5cc3277abb5818cea28c06fe9b3b285d73d06;Subdomain=OneLoginSubDomain;AppId=1433920';Url=https://MyInstance12345.service-now.com/;

PingFederate

PingFederate に接続するには、AuthScheme をPingFederate に設定し、次のプロパティを設定します。

  • User：PingFederate ユーザー。
  • Password：PingFederate ユーザーのパスワード。
  • SSOLoginURL：SSO プロバイダーのログインURL。
  • AWSRoleARN（オプション）：複数のロールARN がある場合は、認可に使用するARN を指定します。
  • AWSPrincipalARN（オプション）：複数のプリンシパルARN がある場合は、認可に使用するARN を指定します。
  • SSOProperties（オプション）：Amazon S3へのリクエストにユーザー名とパスワードを認可ヘッダーとして含める場合は、Authscheme=Basic。

SSOLoginURL 用の相互SSL 認証（WS-Trust STS エンドポイント）を有効化するには、次の SSOProperties を設定します。

  • SSLClientCert
  • SSLClientCertType
  • SSLClientCertSubject
  • SSLClientCertPassword

接続文字列の例： 

AuthScheme=PingFederate;URL='https://dev103586.service-now.com';SSOLoginUrl='https://mycustomserver.com:9033/idp/sts.wst';User=admin;Password=PassValue123;

データの取得

Select-ServiceNow cmdlet はデータを取得するためのネイティブなPowerShell インターフェースを提供します。 

$results = Select-ServiceNow -Connection $conn -Table "incident" -Columns @("sys_id, priority") -Where "category='request'"
Invoke-ServiceNow cmdlet はSQL インターフェースを提供します。このcmdlet を使うと、Query パラメータを介してSQL クエリを実行できます。

cmdlet 出力のパイプ処理

cmdlet は行オブジェクトをパイプラインに一度に一行ずつ返します。以下は、結果をCSV ファイルにエクスポートします。 

Select-ServiceNow -Connection $conn -Table incident -Where "category = 'request'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myincidentData.csv -NoTypeInformation

Select-ServiceNow からの結果をSelect-Object cmdlet にパイプして、Export-CSV cmdlet にパイプする前にいくつかのプロパティを実行していることがわかるでしょう。これをする理由は、CData Cmdlets は接続、テーブル、およびカラムの情報を結果セットの各行オブジェクトに追加しますが、必ずしもその情報がCSV ファイルに必要ではないからです。

ただし、これによってcmdlet の出力を別のcmdlet にパイプすることが容易になります。以下に、結果セットをJSON に変換する例を示します。 

 
PS C:\> $conn  = Connect-ServiceNow -OAuthClientId "MyClientId" -OAuthClientSecret "MyClientSecret" -Password "MyPassword" -User "MyUser" -Url "https://MyInstance12345.service-now.com/"
PS C:\> $row = Select-ServiceNow -Connection $conn -Table "incident" -Columns (sys_id, priority) -Where "category = 'request'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "incident",
  "Columns":  [

  ],
  "sys_id":  "Mysys_id",
  "priority":  "Mypriority"
}

データの削除

以下は、抽出条件に合うあらゆるレコードを削除します。 

Select-ServiceNow -Connection $conn -Table incident -Where "category = 'request'" | Remove-ServiceNow

データの変更

cmdlet はデータクレンジング同様、データの変換を容易にします。次の例は、レコードがすでに存在するかどうか、挿入する前に更新が必要かどうかをチェックしてから、CSV ファイルのデータをServiceNow にロードします。 

Import-Csv -Path C:\MyincidentUpdates.csv | %{
  $record = Select-ServiceNow -Connection $conn -Table incident -Where ("sys_id = `'"+$_.sys_id+"`'")
  if($record){
    Update-ServiceNow -Connection $conn -Table incident -Columns @("sys_id","priority") -Values @($_.sys_id, $_.priority) -Where "sys_id  = `'$_.sys_id`'"
  }else{
    Add-ServiceNow -Connection $conn -Table incident -Columns @("sys_id","priority") -Values @($_.sys_id, $_.priority)
  }
}

Copyright (c) 2024 CData Software, Inc. - All rights reserved.
Build 24.0.9062