Cmdlets for Jira

Build 24.0.9062

接続の確立

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

インストールおよび接続

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

Install-Module JIRACmdlets

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

Import-Module JIRACmdlets;

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

$conn = Connect-JIRA -User 'admin' -APIToken '123abc' -Url 'https://yoursitename.atlassian.net'

Jira への接続

接続するには、URL をJira のエンドポイントに設定します。例えば、https://yoursitename.atlassian.net です。

カスタムフィールドへのアクセス

デフォルトでは、本製品 はシステムフィールドのみ表示します。Issues のカスタムフィールドにアクセスするには、IncludeCustomFields をtrue に設定するか、本製品 スキーマを拡張してカスタムフィールドへのアクセスを設定します。（カスタムフィールド を参照してください。）カスタムフィールドが含まれる場合、サーバーの応答時間が著しく遅くなることがありますのでご注意ください。

Jira への認証

Jira は、個人用アクセストークン、またはOAuth 2.0 による認証をサポートします。

個人用アクセストークン（PAT）

PAT は、Jira を認証するセキュアな方法であり、ユーザー名とパスワードによる認証に代わる安全な代替手段として機能します。PAT による認証の利点は、万が一システムが侵害された場合、管理者が既存のトークンを即座に取り消せることです。これにより、すべてのスクリプトおよびインテグレーションでアクセスパスワードを変更する必要がなくなります。

PAT は各ユーザーによって作成されます。作成されると、自動的にユーザーと同じパーミッションレベルになります。ユーザーはAtlassian Settings メニューから、またはREST API を使用してPAT を作成できます。

Atlassian アプリケーションから：

  1. 画面右上のプロフィール画像を選択します。Jira はドロップダウンリストを表示します。
  2. Settings ->Profile を選択します。
  3. 左パネルで、Personal Access Tokens を選択します。
  4. Create token をクリックします。
  5. 新しいトークンに名前を付けます。
  6. 必要であれば、トークンを一定日数後に自動的に失効するように設定します。（Atlassian はトークンの有効期限が切れる5日前にリマインダーメッセージを表示し、ユーザーに新しいトークンを作成する時間を与えます。）
  7. Create をクリックします。

個人用トークンが表示されます。トークンは作成後に閲覧や検索ができないため、必ずその場でコピーし、安全な場所に保管してください。

次に、以下のJira 本製品 プロパティを設定します。

  • AuthScheme = PAT
  • PAT = 生成された個人用アクセストークンの値。

Note： PAT はREST API を使用して作成することもできます。詳しくは、https://confluence.atlassian.com/enterprise/using-personal-access-tokens-1026032365.html でJira のPAT 作成についてのドキュメントを参照してください。

OAuth 2.0

Jira の"3本足の" OAuth 2.0 サポート（3LO）を活用して、ログインクレデンシャルを提供せずにデータに接続できます。

以下の手順は、すべてのOAuth フローでAuthScheme がOAuth に設定されていることを前提としています。

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

CData は、OAuth デスクトップ認証を簡略化する埋め込みOAuth アプリケーションを提供します。代わりに、カスタムOAuth アプリケーションを作成することも可能です。カスタムアプリケーションの作成およびその理由については、カスタムOAuth アプリケーションの作成 を参照してください。

以下を設定して、接続してください。

  • InitiateOAuth：GETANDREFRESH に設定。InitiateOAuth を使うと、OAuth 交換の繰り返しや、手動でのOAuthAccessToken 設定を避けられます。
  • OAuthClientId（カスタムアプリのみ）：登録時に割り当てられたクライアントId に設定。
  • OAuthClientSecret（カスタムアプリのみ）：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
  • CallbackURL（カスタムアプリのみ）：アプリケーションの登録時に定義されたリダイレクトURI に設定。
  • Url（カスタムアプリのみ）：Jira エンドポイントへのURL に設定。例えば、https://yoursitename.atlassian.net です。
  • OAuthVersion（カスタムアプリのみ）：2.0 に設定。
接続すると、本製品 はデフォルトブラウザでJira のOAuth エンドポイントを開きます。ログインして、アプリケーションにアクセス許可を与えます。 本製品 はアクセストークンの期限が切れると自動的にリフレッシュします。

ヘッドレスマシン

ヘッドレスマシンのユーザーアカウントでOAuth を使用するようにドライバーを設定するには、インターネットブラウザに対応した別の端末で認証する必要があります。

  1. 以下のオプションから選択します。
    • オプション1：後述の「Verifier code を取得および交換」に従い、OAuthVerifier 値を取得します。
    • オプション2：インターネットブラウザに対応したマシンに本製品 をインストールし、後述の「OAuth 設定を転送」の説明に従い、通常のブラウザベースのフローで認証後にOAuth 認証値を転送します。
  2. 次に、ヘッドレスマシンからアクセストークンを自動的にリフレッシュするように本製品 を設定します。

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

Verifier code を取得するには、OAuth Authorization URL で認証する必要があります。

インターネットブラウザに対応したマシンから認証してOAuthVerifier 接続プロパティを取得する方法は次のとおりです。

  1. 以下のオプションから選択します。
    • 埋め込みOAuth アプリケーションを使用する場合は、GetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。
    • カスタムOAuth アプリケーションを使用するには、以下のプロパティを設定します。
      • InitiateOAuth：OFF に設定。
      • OAuthClientId：アプリケーションの登録時に割り当てられたクライアントId に設定。
      • OAuthClientSecret：アプリケーションの登録時に割り当てられたクライアントシークレットに設定。
      • OAuthVersion：2.0 に設定。
      次に、適切なCallbackURL を指定してGetOAuthAuthorizationURL ストアドプロシージャを呼び出します。ストアドプロシージャによって返されたURL をブラウザで開きます。
  2. ログインして、本製品 にアクセス許可を与えます。すると、リダイレクトURI にリダイレクトされます。リダイレクトURI にはcode というパラメータが付加されます。このパラメータの値を控えておきます。後でOAuthVerifier 接続プロパティを設定するために必要です。
次に、OAuth verifier code をOAuth リフレッシュトークンおよびアクセストークンと交換する必要があります。

ヘッドレスマシンでは、次の接続プロパティを設定してOAuth 認証値を取得します。

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

接続をテストしてOAuth 設定ファイルを生成し、以下のプロパティを再設定して接続します。

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

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

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

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

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

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

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

OAuth 1.0

非推奨：OAuth 1.0a は非推奨の認証プロトコルであり、Jira Cloud では使用しないでください。OAuthClientId をOAuthAccessToken 接続プロパティとともに設定することで、OAuth 2.0 バージョンを使用できます。
Jira に接続するには、次の手順に従ってください。

  1. RSA 公開 / 秘密キーのペアを生成します。ターミナルで次のコマンドを実行します。 
    -openssl genrsa -out jira_privatekey.pem 1024
-openssl req -newkey rsa:1024 -x509 -key jira_privatekey.pem -out jira_publickey.cer -days 365
-openssl pkcs8 -topk8 -nocrypt -in jira_privatekey.pem -out jira_privatekey.pcks8
-openssl x509 -pubkey -noout -in jira_publickey.cer  -out jira_publickey.pem
  2. アカウントにアプリケーションリンクを作成します。設定 -> アプリケーション -> アプリケーションのリンクに進みます。
  3. URL フィールドにテストURL を入力し、新しいリンクを作成をクリックします。
  4. エラーを無視して続行をクリックします。必要なのは受信コール（アプリケーションからJira へ）の設定のみです。
  5. Link Applications ウィンドウでは、このタスクと関連性がないため、フィールドの入力は任意です。ただし、受信リンクの作成は選択してください。続行をクリックして次のページに進みます。
  6. 必須フィールドを埋めます。
    • コンシューマーキー：任意の文字列を使用。これはOAuthClientId 接続プロパティで必要です。
    • コンシューマー名：任意の文字列を使用。
    • パブリックキー：先に生成したjira_publickey.pem ファイルのキーを入力。
  7. 続行をクリックします。
接続するには次のプロパティを設定します。

  • URL （例：https://yoursitename.atlassian.net）。
  • OAuthClientId をアプリケーションのConsumer Key に設定。
  • OAuthClientSecret を任意の値（'testClientSecret' など）に設定。
  • CertificateStore を秘密キーファイルの場所に設定。
  • CertificateStoreType を使用されている秘密キーファイルに基づいて適切なオプションに設定。生成されたPEM キーファイルを使用する場合は、CertificateStoreType をPEMKEY_FILE に設定します。
  • InitiateOAuth をGETANDREFRESH に設定。

API トークン

AuthScheme をAPIToken に設定し、User およびAPIToken を設定することで、任意のJira Cloud アカウントへの接続を確立できます。
Cloud インスタンスへのベーシック認証には、API トークンが必要です。API トークンを生成するには、Atlassian アカウントにログインして［セキュリティ設定］->［API トークン］->［API トークンを作成する］をクリックします。生成されたトークンが表示されます。

Basic

AuthScheme をBasic に設定することで、任意のJira Server インスタンスへの接続を確立できます。Server インスタンスに接続するには、User およびPassword を指定します。
（Note：パスワードはCloud アカウントへの接続には非推奨となり、Server インスタンスへの接続にのみ使用されるようになりました。）

LDAP

AuthScheme をLDAP に設定することで、任意のJira Server インスタンスへの接続を確立できます。追加で、Jira インスタンスのURL、User、およびPassword を指定します。 （Note：LDAP 認証は現在、Cloud アカウントではサポートされていません。）

Crowd

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

  • User：Crowd ユーザーアカウント。
  • Password：Crowd アカウントに関連付けられたパスワード。
  • SSOLoginURL：Crowd アカウントに関連付けられたログインURL。IDP URL は、自身のアプリケーション->［SSO］->［SSO information］->［Identity provider single sign-on URL］にあります。
  • SSOAppName：SSO を有効にするアプリケーション名。
  • SSOAppPassword：SSO を有効にするアプリケーションのパスワード。
  • SSOExchangeUrl：The URL used used to exchange the SAML token for Jira cookies. This URL may have the following formats:
    • https://<authority of Jira instance>/plugins/servlet/samlconsumer
    • https://<authority of Jira instance>/plugins/servlet/samlsso

接続文字列の例： 

AuthScheme=Crowd;Url=https://yoursitename.atlassian.net;SSOLoginURL='https://<authority>/crowd/console/secure/saml/sso.action';User=crowdUserName;Password=crowdPassword;SSOExchangeUrl=https://<authority of Jira instance>/plugins/servlet/samlconsumer;SSOAppName=CrowdAppName;SSOAppPassword=CrowdAppPassword;

Okta

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

  • User：Okta ユーザー。
  • Password：Okta ユーザーのパスワード。
  • SSOLoginURL：SSO プロバイダーのログインURL。
  • SSOExchangeUrl: The URL used used to exchange the SAML token for Jira cookies. This URL may have the following formats:
    • https://<authority of Jira instance>/plugins/servlet/samlconsumer
    • https://<authority of Jira instance>/plugins/servlet/samlsso

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;Url=https://yoursitename.atlassian.net;SSOLoginURL='https://example.okta.com/home/appType/0bg4ivz6cJRZgCz5d6/46';User=oktaUserName;Password=oktaPassword;SSOExchangeUrl=https://<authority of Jira instance>/plugins/servlet/samlconsumer;

データの取得

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

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

cmdlet 出力のパイプ処理

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

Select-JIRA -Connection $conn -Table Projects -Where "Id = '10000'" | Select -Property * -ExcludeProperty Connection,Table,Columns | Export-Csv -Path c:\myProjectsData.csv -NoTypeInformation

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

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

 
PS C:\> $conn  = Connect-JIRA -User 'admin' -APIToken '123abc' -Url 'https://yoursitename.atlassian.net'
PS C:\> $row = Select-JIRA -Connection $conn -Table "Projects" -Columns (Key, Name) -Where "Id = '10000'" | select -first 1
PS C:\> $row | ConvertTo-Json
{
  "Connection":  {

  },
  "Table":  "Projects",
  "Columns":  [

  ],
  "Key":  "MyKey",
  "Name":  "MyName"
}

データの削除

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

Select-JIRA -Connection $conn -Table Projects -Where "Id = '10000'" | Remove-JIRA

データの変更

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

Import-Csv -Path C:\MyProjectsUpdates.csv | %{
  $record = Select-JIRA -Connection $conn -Table Projects -Where ("Id = `'"+$_.Id+"`'")
  if($record){
    Update-JIRA -Connection $conn -Table Projects -Columns @("Key","Name") -Values @($_.Key, $_.Name) -Where "Id  = `'$_.Id`'"
  }else{
    Add-JIRA -Connection $conn -Table Projects -Columns @("Key","Name") -Values @($_.Key, $_.Name)
  }
}

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