接続の確立

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 への接続

データに接続する前に、認証ユーザーが、最低でもメタデータの一覧表示に必要な次の権限を割り当てられていることを確認する必要があります。これを行う前に、アカウントの管理者は、［ユーザー］メニュー->［ロールを昇格］->［security_admin］チェックボックスをON にし、［OK］に移動して、ロールを昇格する必要があります。以下にリストされているテーブルの場合、ユーザーはsys_db_object やsys_glide_object のような行レベルの権限と、sys_db_object.* やsys_glide_object.* のようなフィールドレベルの権限の両方を持っている必要があります。ユーザーがアクセスを希望する追加のテーブルについては、少なくとも行レベルの権限が必要です。

Url 接続プロパティは、すべての接続に必須のプロパティです。

READ sys_db_object

データに接続するには、sys_db_object へのアクセスが必須です。次のようにしてアクセスを有効にできます。

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

READ sys_glide_object

特定のServiceNow テーブルメタデータには、sys_glide_object へのアクセスが必要です。前述の手順を繰り返すことで、これに対するアクセスを有効にできます。ただし手順4で、ACL の名前には［フィールドクラス[sys_glide_object]］を選択してください。

READ sys_dictionary

sys_dictionary へのアクセスは、ServiceNow からスキーマ情報を取得するために必須です。［ユーザー管理］->［ユーザー］->［Select authenticating user］->［ロール］->［編集...］ に移動し、コレクションから"personalize_dictionary" ロールを追加することでこれに対するアクセスを有効にできます。

ServiceNow への認証

Basic

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

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

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

OAuth の使用

ServiceNow はOAuth 2.0 認証標準を利用しています。OAuth を使って認証するには、ServiceNow にOAuth アプリを登録してOAuthClientId を取得しなければなりません。OAuth 値の他に、Url、User、およびPassword の指定が必要です。

OAuth 認証を介した接続について詳しくは、OAuth 認証の使用を参照してください。

ADFS

AuthScheme をADFS に設定します。次の接続プロパティを設定する必要があります。

User：ADFS ユーザーに設定。
Password：ユーザーのADFS パスワードに設定。
SSOLoginURL：SSO プロバイダーが使用するログインURL に設定。

ADFS への認証には、次のSSOProperties が必要です。

RelyingParty：この属性は、ServiceNow の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

AuthScheme をOkta に設定します。Okta を介した認証には、次の接続プロパティを使用します。

User：Okta ユーザーに設定。
Password：Okta パスワードに設定。
SSOLoginURL：SSO プロバイダーが使用するログインURL に設定。

以下の場合、

Okta クライアントリクエストコンテキストをオーバーライドする信頼されたアプリケーションまたはプロキシ経由でユーザーを認証する
MFA を構成する

Okta を使用して認証するためには、SSOProperties 入力パラメータの組み合わせを使用する必要があります。それ以外の場合、これらの値を設定する必要はありません。

SSOProperties に、必要に応じて以下の入力パラメータを設定します。

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

接続文字列の例：

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

OneLogin

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

User：OneLogin ユーザーに設定。
Password：ユーザーのOneLogin パスワードに設定。

次のSSOProperties がOneLogin への認証に必要です。

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 に設定。
Region（オプション）：OneLogin アカウントで使用しているリージョンに設定。OneLogin API は複数のリージョンで動作し、このプロパティは正しいドメインを見つけるために使用されます。次の値の1つを取ります。
- US（デフォルト）
- EU

次は接続文字列の例です。次の接続文字列はOneLogin への接続にAPI キーを使います。

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

PingFederate

AuthScheme をPingFederate に設定します。次の接続プロパティを設定する必要があります。

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

追加で次のSSOProperties を使って、SSOLoginURL 用の相互SSL 認証（WS-Trust STS エンドポイント）の設定が可能です。

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

Cmdlets for ServiceNow