DevOps API

DevOps - GET /devops/code/schema

指定されたコードリソース (コミット、リポジトリ、または分岐) のスキーマオブジェクトを返します。

必要なスキーマオブジェクトを取得したら、それを使用して、対応する POST 呼び出しの要求本文を作成します (POST /code/commit、POST /code/repository、または POST /code/branch)。

注:

このエンドポイントは、必要な要求本文要素のみを返します。

URL 形式

バージョニングされた URL： /api/sn_devops/{api_version}/devops/code/schema

デフォルト URL： /api/sn_devops/devops/code/schema

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 1. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 2. クエリパラメーター
名前	説明
resource	必須です。返されるリソーススキーマのタイプ。有効な値 (値の大文字と小文字を区別しない)：分岐 commit リポジトリデータタイプ：文字列

表 : 3. 要求本文パラメーター (XML または JSON)
名前	説明
なし

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 4. 要求ヘッダー
ヘッダー	説明
Accept	応答本文のデータフォーマット。application/json のみをサポートします。

表 : 5. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 6. ステータスコード
ステータスコード	説明
200	要求が正常に完了しました。
401	認証が無効か見つかりません。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


名前	説明
branch	コードのコミットが行われたブランチの説明。データタイプ：オブジェクト `"branch": { "name": "String", "path": "String" }`
branch.name	コードのコミットが行われたブランチの名前。データタイプ：文字列
branch.path	ブランチの相対パス。データタイプ：文字列
コミット	コミットの説明。データタイプ：オブジェクトのアレイ `"commits": [ { "committedDate": "String", "committer": {Object}, "details": [Array], "id": "String", "url": "String" } ]`
commits.committedDate	ソースツールでコードがコミットされた日時DevOps データタイプ：文字列形式：ISO 8601 (タイムゾーンオフセットあり) 例：1970-01-01T08:15:30-05:00
commits.committer	コミットを要求したユーザー/エンティティの説明。データタイプ：オブジェクト `"committer": { "email": "String" }`
commits.committer.email	コミットを要求したユーザーのメールアドレス。データタイプ：文字列
commits.details	コミットの詳細。注: コミットに詳細を含めることは必須ではありません。このエンドポイントは、詳細がコミットに含まれていない場合、空のアレイを返します。データタイプ：オブジェクトのアレイ `"details": [ { "action": "String", "additions": Number, "changes": Number, "deletions": Number, "file": "String", "totalChanges": Number } ]`
commits.details.action	ファイルに対して実行されたアクション。データタイプ：文字列
commits.details.additions	ファイル内の追加の合計数。データタイプ：数値
commits.details.changes	行われた変更の合計数。データタイプ：数値
commits.details.deletions	ファイル内の削除の合計数。データタイプ：数値
commits.details.file	ブランチに対して相対的に変更されたファイルのパス。データタイプ：文字列
commits.details.totalChanges	追加と削除の合計数。データタイプ：数値
commits.id	ソースプラットフォーム識別子またはコミット SHA。データタイプ：文字列
commits.url	コミットの URL (「https://github.com/mycompany/mobileplatform/commit/3fa85f6457174562b3fc2c963f66afa6」など)。データタイプ：文字列
name	分岐またはリポジトリの名前 (「Master」や「Platform-Mobile」など)。データタイプ：文字列
path	ブランチの相対パス。データタイプ：文字列
repository	コミットが行われたリポジトリの説明。データタイプ：オブジェクト `"repository": { "name": "String", "url": "String" }`
repository.name	リポジトリの名前。データタイプ：文字列
repository.url	ソース DevOps ツールのリポジトリの URL。データタイプ：文字列
url	リポジトリの URL (「https://github.com/mycompany/mobileplatform」など)。データタイプ：文字列

resource=branch のサンプル cURL 要求

curl "https://instance.servicenow.com/api/sn_devops/v1/devops/code/schema?resource=branch" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
   "result": {
      "name": "Master",
      "path": "refs/heads/master",
      "repository": {
         "name": "Platform-Mobile",
         "url": "https://github.com/mycompany/mobileplatform"
      }
   }
}

resource=commit のサンプル cURL 要求

curl "https://instance.servicenow.com/api/sn_devops/v1/devops/code/schema?resource=commit" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
   "result": {
      "repository": {
         "name": "Platform-Mobile",
         "url": "https://github.com/mycompany/mobileplatform"
      },
      "branch": {
         "name": "refs/heads/master"
      },
      "commits": [
         {
            "committer": {
               "email": "name@email.com"
            },
            "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
            "url": "https://github.com/mycompany/mobileplatform/commit/3fa85f6457174562b3fc2c963f66afa6",
            "committedDate": "2022-01-01T08:15:30-05:00",
            "details": [
               {
                  "action": "edit",
                  "changes": "",
                  "file": "/azure-pipelines.yml",
                  "additions": 1,
                  "deletions": 0,
                  "totalChanges": 1
               }
            ]
         }
      ]
   }
}

resource=repository のサンプル cURL 要求

curl "https://instance.servicenow.com/api/sn_devops/v1/devops/code/schema?resource=repository" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
    "result": {
        "name": "Platform-Mobile",
        "url": "https://github.com/mycompany/mobileplatform"
    }
}

DevOps - GET /devops/onboarding/status

DevOps サービスによって処理されている、または非同期に処理されている、指定されたオンボーディングイベントの現在のステータスを返します。

URL 形式

バージョニングされた URL： /api/sn_devops/{api_version}/devops/onboarding/status

デフォルト URL：/api/sn_devops/devops/onboarding/status

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 7. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 8. クエリパラメーター
名前	説明
id	ステータスを返すオンボーディングイベントの一意の識別子。この値は、イベント要求を呼び出したエンドポイントの結果として返されます (/devops/onboarding/app や /devops/onboarding/tool など)。データタイプ：文字列

表 : 9. 要求本文パラメーター
名前	説明
なし

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 10. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。

表 : 11. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 12. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
202	処理待ち：オンボーディング要求が作成され、DevOps サービスが要求を処理しています。
207	部分的に成功：オンボーディング要求が作成され、DevOps サービスで要求が処理されます。
400	失敗：オンボーディングイベントが失敗しました。
404	失敗：エンドポイントは、指定されたイベント ID に一致する要求を見つけることができませんでした。

応答本文のパラメーター


名前	説明
result	オンボーディング要求の結果。データタイプ：オブジェクト `"result": { "code": "String", "importRequestsSysIds": "[Array], "messageDetails": {Object], "onboardingRequestID": "String", "status": "String" }`
result.code	HTTP ステータスコード。データタイプ：文字列
result.importRequestsSysIds	オンボーディング要求の一部として作成されたインポート要求のリスト。データタイプ：文字列のアレイ
result.messageDetails	オンボーディングイベントの進捗状況の詳細。データタイプ：オブジェクト `"messageDetails": { "apps": [Array], "pipelines": [Array], "plans": [Array], "repositories": [Array], "status": "String", "toolResponse": [Array] }`
result.messageDetails.apps	関連付けられた ServiceNow インスタンス内で作成するアプリを定義します。データタイプ：オブジェクトのアレイ `"apps": [{ "appId": "String", "message": "String", "name": "String", "status": "String", }]`
result.messageDetails.apps.appId	アプリケーションのオンボーディング時に生成されたアプリケーションの sys_id。データタイプ：文字列テーブル:アプリ [sn_devops_app]
result.messageDetails.apps.message	アプリケーションのオンボーディングのステータスを説明するメッセージ。データタイプ：文字列
result.messageDetails.apps.name	オンボーディングされるアプリケーションの名前。データタイプ：文字列
result.messageDetails.apps.status	アプリケーションオンボーディングの現在のステータス。可能な値：失敗部分的に成功成功データタイプ：文字列
result.messageDetails.pipelines	オンボーディングイベントに関連付けられたパイプラインのリストとそれに対応する詳細。データタイプ：オブジェクトのアレイ `"pipelines": [{ "changeStepAssociation": [Array], "errors": "String", "message": "String", "name": "String", "status": "String", }]`
result.messageDetails.pipelines.changeStepAssociation	オンボーディングに関連付けられている変更ステップを記述するオブジェクトのアレイ。データタイプ：オブジェクトのアレイ `"changeStepAssociation": [{ "changeStepName": "String", "status": "String", "summary": "String", }]`
result.messageDetails.pipelines.changeStepAssociation.changeStepName	変更ステップの名前。データタイプ：文字列
result.messageDetails.pipelines.changeStepAssociation.status	パイプラインへの変更ステップの関連付けのステータス。可能な値：失敗成功データタイプ：文字列
result.messageDetails.pipelines.changeStepAssociation.summary	変更ステップの関連付けのステータスの概要。データタイプ：文字列
result.messageDetails.pipelines.errors	パイプラインの関連付け時に検出されたエラーのリスト。データタイプ：アレイ
result.messageDetails.pipelines.message	パイプラインの関連付けのステータスを説明するメッセージ。データタイプ：文字列
result.messageDetails.pipelines.name	パイプラインの名前。データタイプ：文字列
result.messageDetails.pipelines.status	パイプラインの関連付けのステータス。データタイプ：文字列
result.messageDetails.plans	オンボーディングイベントに関連付けられた計画のリストとそれに対応する詳細。データタイプ：オブジェクトのアレイ `"plans": [{ "errors": "String", "message": "String", "name": "String", "status": "String", }]`
result.messageDetails.plans.errors	計画の関連付け時に検出されたエラーのリスト。データタイプ：アレイ
result.messageDetails.plans.message	パイプラインの関連付けのステータスを説明するメッセージ。データタイプ：文字列
result.messageDetails.plans.name	計画の名前データタイプ：文字列
result.messageDetails.plans.status	計画の関連付けのステータス。データタイプ：文字列
result.messageDetails.repositories	オンボーディングイベントに関連付けられたリポジトリのリストとそれに対応する詳細。データタイプ：オブジェクトのアレイ `"repositories": [{ "configureStatus": {Object}, "name": "String", "status": "String", }]`
result.messageDetails.repositories.configureStatus	リポジトリの Webhook 構成ステータスの詳細。データタイプ：オブジェクト `"configureStatus": { "message": "String", "status": "String", }`
result.messageDetails.repositories.configureStatus.message	現在の Webhook 構成ステータスを説明するメッセージ。データタイプ：文字列
result.messageDetails.repositories.configureStatus.status	Webhook 構成のステータス。データタイプ：文字列
result.messageDetails.repositories.message	現在のリポジトリの関連付けのステータスを説明するメッセージ。データタイプ：文字列
result.messageDetails.repositories.name	リポジトリの名前。データタイプ：文字列
result.messageDetails.repositories.status	リポジトリの関連付けのステータス。データタイプ：文字列
result.messageDetails.status	オンボーディング要求のステータス。可能な値：失敗部分的に成功成功データタイプ：文字列
result.messageDetails.toolResponse	関連する ServiceNow インスタンス内でオンボーディングするツールのリスト。データタイプ：オブジェクトのアレイ `"toolResponse": [{ "configureStatus": {Object}, "connectStatus": {Object}, "createStatus": {Object}, "discoveryStatus": {Object}, "name": "String", "status": "String", "type": "String" }]`
result.messageDetails.toolResponse.configureStatus	ツールの構成ステータス。成功した場合は、status および message を返します。エラーの場合は、status および error を返します。データタイプ：オブジェクト `"configureStatus": { "error": "String", "message": "String", "status": "String" }`
result.messageDetails.toolResponse.configureStatus.error	ツールの構成中に検出されたエラー。データタイプ：文字列
result.messageDetails.toolResponse.configureStatus.message	ツール構成の成功ステータスを説明するメッセージ。データタイプ：文字列
result.messageDetails.toolResponse.configureStatus.status	ツール構成のステータス。データタイプ：文字列
result.messageDetails.toolResponse.connectStatus	ツールの接続ステータス。成功した場合は、status および message を返します。エラーの場合は、status および error を返します。データタイプ：オブジェクト `"connectStatus": { "error": "String", "message": "String", "status": "String" }`
result.messageDetails.toolResponse.connectStatus.error	ツールの接続中に検出されたエラー。データタイプ：文字列
result.messageDetails.toolResponse.connectStatus.message	ツール接続の成功ステータスを説明するメッセージ。データタイプ：文字列
result.messageDetails.toolResponse.connectStatus.status	ツール接続のステータス。データタイプ：文字列
result.messageDetails.toolResponse.createStatus	ツールの作成ステータス。成功した場合は、status および message を返します。エラーの場合は、status および error を返します。データタイプ：オブジェクト `"createStatus": { "error": "String", "message": "String", "status": "String" }`
result.messageDetails.toolResponse.createStatus.error	ツールの作成中に検出されたエラー。データタイプ：文字列
result.messageDetails.toolResponse.createStatus.message	ツール作成の成功ステータスを説明するメッセージ。データタイプ：文字列
result.messageDetails.toolResponse.createStatus.status	ツール作成のステータス。データタイプ：文字列
result.messageDetails.toolResponse.discoveryStatus	ツールのディスカバリーステータス。成功した場合は、status および message を返します。エラーの場合は、status および error を返します。データタイプ：オブジェクト `"discoveryStatus": { "error": "String", "imports: [Array], "message": "String", "status": "String" }`
result.messageDetails.toolResponse.discoveryStatus.error	ツールの検出中に検出されたエラー。データタイプ：文字列
result.messageDetails.toolResponse.discoveryStatus.imports	検出されたエンティティのリスト。データタイプ：オブジェクトのアレイ `"imports": [{ "details": "String", "id": "String", "status": "String" }]`
result.messageDetails.toolResponse.discoveryStatus.imports.details	実行されたインポートを説明する詳細。データタイプ：文字列
result.messageDetails.toolResponse.discoveryStatus.imports.id	インポート要求の sys_id。データタイプ：文字列テーブル:sn_devops_m2m_inbound_event_import_request
result.messageDetails.toolResponse.discoveryStatus.imports.status	インポートのステータス。データタイプ：文字列
result.messageDetails.toolResponse.discoveryStatus.message	ツール検出のステータスを説明するメッセージ。データタイプ：文字列
result.messageDetails.toolResponse.discoveryStatus.status	ツール検出のステータス。データタイプ：文字列
result.messageDetails.toolResponse.name	オンボーディングされるツールの名前。データタイプ：文字列
result.messageDetails.toolResponse.status	ツールオンボーディングのステータス。データタイプ：文字列
result.messageDetails.toolResponse.type	ツールのタイプ (Jira や Jenkins など)。データタイプ：文字列
result.onboardingRequestID	オンボーディング要求の一意の識別子。/devops/onboarding/status エンドポイントを呼び出して、関連するツールのオンボーディングプロセスのステータスを取得するときに、この値を使用します。データタイプ：文字列
result.status	オンボーディング要求のステータス。可能な値：失敗部分的に成功成功データタイプ：文字列

cURL 要求

次の例は、ツールオンボーディングのステータス要求を示しています。

curl -X GET "https://servicenow-instance/api/sn_devops/v1/devops/onboarding/status?id=IBE0001603" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u "username":"password" \

{
    "result": {
        "code": "207",
        "onboardingRequestID": "IBE0001603",
        "status": "partial-success",
        "messageDetails": {
            "status": "Partial Success",
            "toolResponse": [
                {
                    "name": "Primary Azure",
                    "type": "Azure DevOps",
                    "status": "Partial Success",
                    "createStatus": {
                        "status": "Success",
                        "message": "Created successfully"
                    },
                    "connectStatus": {
                        "status": "Failed",
                        "error": "Method failed: (/testFirst/_apis/work/boards) with code: 401 - Invalid username/password combo"
                    }
                },
                {
                    "name": "Primary Jenkins",
                    "type": "Jenkins",
                    "status": "Success",
                    "createStatus": {
                        "status": "Success",
                        "message": "Created successfully"
                    },
                    "connectStatus": {
                        "status": "Success",
                        "message": "Connected successfully"
                    },
                    "discoveryStatus": {
                        "status": "Success",
                        "message": "Discovered successfully",
                        "imports": [
                            {
                                "status": "completed",
                                "id": "2a4d216bdb2d2450fe4fd6a75e9619c3",
                                "details": "Discovered 1 new job(s) and 3 new pipeline(s)\n"
                            }
                        ]
                    }
                },
                {
                    "name": "Primary GitHub",
                    "type": "GitHub",
                    "status": "Success",
                    "createStatus": {
                        "status": "Success",
                        "message": "Created successfully"
                    },
                    "connectStatus": {
                        "status": "Success",
                        "message": "Connected successfully"
                    },
                    "discoveryStatus": {
                        "status": "Success",
                        "message": "Discovered successfully",
                        "imports": [
                            {
                                "status": "completed",
                                "id": "7f4d616bdb2d2450fe4fd6a75e9619c2",
                                "details": "Discovered 5 new repositories. "
                            }
                        ]
                    }
                },
                {
                    "name": "Primary Bitbucket",
                    "type": "BitBucket",
                    "status": "Success",
                    "createStatus": {
                        "status": "Success",
                        "message": "Created successfully"
                    },
                    "connectStatus": {
                        "status": "Success",
                        "message": "Connected successfully"
                    },
                    "discoveryStatus": {
                        "status": "Success",
                        "message": "Discovered successfully",
                        "imports": [
                            {
                                "status": "completed",
                                "id": "815da16bdb2d2450fe4fd6a75e9619d0",
                                "details": "Discovered 11 new repositories. "
                            }
                        ]
                    }
                },
                {
                    "name": "Primary Gitlab",
                    "type": "GitLab",
                    "status": "Partial Success",
                    "createStatus": {
                        "status": "Success",
                        "message": "Created successfully"
                    },
                    "connectStatus": {
                        "status": "Failed",
                        "error": "The current operation ended in state: ERROR"
                    }
                }
            ],
            "importRequestsSysIds": [
                "2a4d216bdb2d2450fe4fd6a75e9619c3",
                "7f4d616bdb2d2450fe4fd6a75e9619c2",
                "815da16bdb2d2450fe4fd6a75e9619d0"
            ]
        }
    }
}

cURL 要求

次の例は、アプリケーションオンボーディングのステータス要求を示しています。

curl -X POST "https://servicenow-instance/api/sn_devops/v1/devops/onboarding/status?onboardingRequestID=IBE0001604" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u "username":"password" \

{
    "result": {
        "code": "207",
        "onboardingRequestID": "IBE0001604",
        "status": "partial-success",
        "messageDetails": {
            "status": "Partial Success",
            "apps": [
                {
                    "name": "Bike Rentals Service",
                    "status": "Success",
                    "appId": "c7fd696bdb2d2450fe4fd6a75e961993",
                    "message": "App by name 'Bike Rentals Service' has been successfully created"
                }
            ],
            "pipelines": [
                {
                    "name": "Bike Rentals",
                    "status": "Success",
                    "message": "Successfully associated with app 'Bike Rentals Service'",
                    "changeStepAssociation": [
                        {
                            "status": "Success",
                            "changeStepName": "Prod",
                            "summary": "Change step with name 'Prod' has been created"
                        }
                    ]
                }
            ],
            "repositories": [
                {
                    "name": "nowdevops01/BikeRentals",
                    "status": "Partial Success",
                    "message": "Successfully associated with app 'Bike Rentals Service'",
                    "configureStatus": {
                        "status": "Failed",
                        "message": "Webhook configuration failed due to empty credentials for repository by name nowdevops01/BikeRentals in tool Primary GitHub"
                    }
                }
            ],
            "plans": [
                {
                    "status": "Failed",
                    "name": "testFirst",
                    "errors": [
                        "Plan by name 'testFirst' does not exist in tool Primary Azure"
                    ]
                }
            ]
        }
    }
}

DevOps - GET /devops/orchestration/changeControl

オーケストレーションタスクが変更管理下にあるかどうかを確認します。

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/orchestration/changeControl

デフォルトの URL：/api/sn_devops/devops/orchestration/changeControl

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 13. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 14. クエリパラメーター
名前	説明
orchestrationTaskName	確認するオーケストレーションタスクの名前。データタイプ：文字列
testConnection	インスタンスと DevOps ツール間のエンドツーエンド接続をテストするかどうかを示すフラグ。有効な値： true：エンドツーエンド接続をテストします。 false:エンドツーエンド接続をテストしません。データタイプ：ブーリアンデフォルト値：false
toolId	必須です。オーケストレーションツールの sys_id。データタイプ：文字列テーブル:オーケストレーションツール [sn_devops_orchestration_tool]
toolType	ツールのタイプ。有効な値：jenkins データタイプ：文字列

表 : 15. 要求本文パラメーター
名前	説明
なし

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 16. 要求ヘッダー
ヘッダー	説明
Accept	応答本文のデータフォーマット。application/json のみをサポートします。
認証	v2 以降、この API はトークンベースの認証をサポートしています。トークンは、ツール [sn_devops_tool] テーブルにあるツールレコードの [ トークンのコピー ] ボタンをクリックして取得できます。トークンは、Authorization: の形式で認証ヘッダーで使用できます `sn_devops。DevOpsToken <tool_sys_id>:<tool_token>`。注: 基本認証の詳細 (ユーザー名とパスワード) がトークン付きの認証ヘッダーに加えて指定されている場合、基本認証が優先されます。 devops.systemユーザーがインスタンスで利用できない場合は、[トークンベースの認証が成功した後にこのユーザーに切り替え] プロパティを使用します。このプロパティを使用すると、トークン認証を完了するために必要な sn_devops.integration ロールを持つユーザーを設定できます。詳細については、「DevOps Change Velocity properties」を参照してください。

表 : 17. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 18. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
401	認証が無効か見つかりません。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター (JSON または XML)


名前	説明
changeControl	オーケストレーションタスクが変更管理下にあるかどうかを示すフラグ。可能な値： true：変更管理下にあります。 false：変更管理下にありません。データタイプ：ブーリアン

変更管理下および API v2 の使用

curl -X GET "https://instance.servicenow.com/api/sn_devops/v2/devops/orchestration/changeControl?toolId=1c219f7e8708f1508ca933383cbb3543&orchestrationTaskName=Platform-Analytics-UAT-Deployment&orchestrationTaskURL=https%253A%252F%252Fjenkins.mycompany.com%253A8080%252Fjob%252FMobile-Platform-deploy%252F&toolType=jenkins" 
-H "accept: application/json"\
-H "Authorization: sn_devops.DevOpsToken 1c219f7e8708f1508ca933383cbb3543:FtN13dfDuahYEtdfDvhHorh0QPp9na3u"

応答本文。

{
"result": {
  "changeControl": true,
  "status": "Success" 
  } 
}

変更管理下になく、API v1 を使用中

curl -X GET "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/changeControl?toolId=f0ca45679323008b52f3b457415ae6&orchestrationTaskName=Platform-Analytics-UAT-Deployment&orchestrationTaskURL=https%253A%252F%252Fjenkins.mycompany.com%253A8080%252Fjob%252FMobile-Platform-deploy%252F&toolType=jenkins" 
-H "accept: application/json"\
-u "username":"password"

応答本文。

{
    "result": {
        "changeControl": false
    }
}

DevOps - GET /devops/orchestration/changeInfo

指定されたオーケストレーションパイプライン実行の変更要求の詳細を取得します。

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/orchestration/changeInfo

デフォルトの URL：/api/sn_devops/devops/orchestration/changeInfo

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 19. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 20. クエリパラメーター
名前	説明
branchName	オーケストレーションタスクに関連付けられた分岐の名前。注: 複数分岐パイプラインを参照する場合は、このパラメーターを指定する必要があります。指定しないと、応答に誤った変更の詳細が含まれる可能性があります。データタイプ：文字列
buildNumber	必須です。オーケストレーションツール内のパイプラインビルド番号。データタイプ：文字列
pipelineName	Jenkins Freestyle または Maven プロジェクトの場合はオプションですが、それ以外の場合は必須です。オーケストレーションパイプライン名。データタイプ：文字列
projectName	Jenkins Freestyle または Maven プロジェクトの場合は必須ですが、それ以外の場合はオプションです。オーケストレーションツールのプロジェクト名。データタイプ：文字列
stageName	Jenkins Freestyle または Maven プロジェクトの場合はオプションですが、それ以外の場合は必須です。オーケストレーションステージ名。データタイプ：文字列最大長：160
toolId	必須です。オーケストレーションツールの sys_id。データタイプ：文字列テーブル:オーケストレーションツール [sn_devops_orchestration_tool]

表 : 21. 要求本文パラメーター (XML または JSON)
名前	説明
なし

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 22. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。
認証	v2 以降、この API はトークンベースの認証をサポートしています。トークンは、ツール [sn_devops_tool] テーブルにあるツールレコードの [ トークンのコピー ] ボタンをクリックして取得できます。トークンは、Authorization: の形式で認証ヘッダーで使用できます `sn_devops。DevOpsToken <tool_sys_id>:<tool_token>`。注: 基本認証の詳細 (ユーザー名とパスワード) がトークン付きの認証ヘッダーに加えて指定されている場合、基本認証が優先されます。 devops.systemユーザーがインスタンスで利用できない場合は、[トークンベースの認証が成功した後にこのユーザーに切り替え] プロパティを使用します。このプロパティを使用すると、トークン認証を完了するために必要な sn_devops.integration ロールを持つユーザーを設定できます。詳細については、「DevOps Change Velocity properties」を参照してください。

表 : 23. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 24. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
404	見つかりません。要求されたアイテムが見つかりませんでした。

応答本文のパラメーター (JSON または XML)


名前	説明
changeFound	変更要求が見つかったかどうかを示すフラグ。可能な値： true：変更要求が見つかりました。 false:変更要求が見つかりませんでした。データタイプ：ブーリアン
number	変更要求番号。データタイプ：文字列
phase	現在のフェーズ。データタイプ：文字列
phase_state	現在のフェーズのステータス。データタイプ：文字列
priority	変更要求の優先度。優先度は、要求の影響度と緊急度に基づいています。Service Desk が要求をどの程度迅速に対処すべきかを示します。可能な値： 1：重大 2：高 3：中 4：低データタイプ：文字列
risk	変更のリスクのレベル。可能な値：低高中データタイプ：文字列
state	変更要求のステータス。可能な値：評価許可キャンセルクローズ済み実装新規評価スケジュール済みデータタイプ：文字列デフォルト：New
sys_id	変更要求の sys_id。データタイプ：文字列
type	変更要求のタイプ。可能な値：緊急通常標準データタイプ：文字列
url	関連する ServiceNow インスタンス内の変更要求の URL。データタイプ：文字列

cURL 要求

curl -X GET "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/changeInfo?toolId=1487f457db642810765555535e9619d3&pipelineName=Automation/apps HR/family release&stageName=deployfamilyrelease&buildNumber=1639"  
-H "accept: application/json"\ 
-u "username":"password"

{  
  "result": {  
    "changeFound": true,  
    "sys_id": "ee89341bdb642810765555535e96196e",  
    "number": "CHG0030001",  
    "type": "normal",  
    "state": "0",  
    "phase": "requested",  
    "phase_state": "open",  
    "priority": "4",  
    "risk": "4",  
    "url": "https://instance.servicenow.com/change_request.do?sys_id=ee89341bdb642810765555535e96196e",  
    "changeAssignmentGroup": "Change Management", 
    "changeApprovers": "Ron Kettering, Christen Mitchell, Howard Johnson, Luke Wilson", 
    "plannedStartDate": "2023-02-05 08:00:00", 
    "plannedEndDate": "2024-02-05 08:00:00" 
  }  
}

DevOps - GET /devops/orchestration/schema

指定されたオーケストレーションリソースのスキーマオブジェクトを返します。

必要なスキーマオブジェクトを取得したら、それを使用して、対応する POST 呼び出しの要求本文を作成します (/orchestration/orchestrationTask または /orchestration/taskExecution)。

注:

このエンドポイントは、必要な要求本文要素のみを返します。

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/orchestration/schema

デフォルトの URL：/api/sn_devops/devops/orchestration/schema

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 25. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 26. クエリパラメーター
名前	説明
resource	返されるリソーススキーマのタイプ。有効な値 (値の大文字と小文字を区別しない)： build_details callback orchestration_task task_execution データタイプ：文字列

表 : 27. 要求本文パラメーター
名前	説明
なし

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 28. 要求ヘッダー
ヘッダー	説明
Accept	応答本文のデータフォーマット。application/json のみをサポートします。

表 : 29. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 30. ステータスコード
ステータスコード	説明
200	要求が正常に完了しました。
401	認証が無効か見つかりません。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


名前	説明
callbackURL	コールバックの URL。データタイプ：文字列
endDateTime	タスク実行が終了した日時。データタイプ：文字列
name	オーケストレーションタスクの名前。データタイプ：文字列
number	タスクの実行数。インシデント番号と同じです。データタイプ：文字列
orchestrationTaskDetails	オーケストレーションタスクの説明。データタイプ：オブジェクト `"orchestrationTaskDetails": { "message": "String", "name": "String", "triggerType": "String", "url": "String" }`
orchestrationTaskDetails.message	自由形式のテキストメッセージ。データタイプ：文字列
orchestrationTaskDetails.name	オーケストレーションタスクの名前。データタイプ：文字列
orchestrationTaskDetails.triggerType	オーケストレーションタスクが開始された方法。データタイプ：文字列
orchestrationTaskDetails.url	関連するオーケストレーションツールのオーケストレーションタスクの URL。データタイプ：文字列
orchestrationTaskURL	オーケストレーションタスクの URL。データタイプ：文字列
result	タスク実行の実行結果。有効な値：失敗成功データタイプ：文字列
startDateTime	タスク実行が開始された日時。データタイプ：文字列
taskExecutionURL	実行するタスクの URL。データタイプ：文字列
triggerType	オーケストレーションタスクが開始された方法。有効な値： scm：Git/scm ツールのコードコミットによってジョブがトリガーされました。 upstream：アップストリームのジョブがこのジョブをトリガーしました。 user：ユーザーが手動でジョブを開始しました。データタイプ：文字列
url	関連するオーケストレーションツールのオーケストレーションタスクの URL。データタイプ：文字列

resource=task_execution によるサンプル cURL 要求

curl -X GET \
'https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/schema?resource=task_execution' \
-H 'Accept: application/json'\
-u 'username':'password'

{
"result": {
  "number": 40,
  "url": "https://jenkins.mycompany.com:8080/job/Mobile-Platform-CI/40/",
  "startDateTime": "1970-01-01T08:15:30-05:00",
  "endDateTime": "1970-01-01T08:25:30-05:00",
  "triggerType": "upstream",
  "result": "Success",
  "orchestrationTaskDetails": {
    "name": "Mobile-Platform-CI",
    "url": "https://jenkins.mycompany.com:8080/job/Mobile-Platform-CI/"
    }
  }
}

resource=orchestration_task によるサンプル cURL 要求

curl -X GET \ 
'https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/schema?resource=orchestration_task' \
-H 'Accept: application/json'\
-u 'username':'password'

{ 
"result": { 
  "name": "Mobile-Platform-CI", 
  "url": "https://jenkins.mycompnay.com:8080/job/Mobile-Platform-CI/" 
  } 
}

resource=callback によるサンプル cURL 要求

curl -X GET \
'https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/schema?resource=task_execution' \
-H 'Accept: application/json' \
-u 'username':'password'

{ 
  "result": { 
    "callbackURL": "http://127.0.0.1:8090/jenkins/sn-devops/9b0feb79-f0b9-4661-83ef-2861b8924784", 
    "orchestrationTaskURL": "http://127.0.0.1:8090/jenkins/job/felipe-downstream/", 
    "orchestrationTaskDetails": { 
      "message": "Started by upstream project \"felipe-upstream\" build number 27", 
      "triggerType": "upstream" 
    } 
  } 
}

DevOps - GET /devops/orchestration/stepMapping

渡される情報がオーケストレーションタスクの作成に有効であり、以前に作成されたステップへの関連付けに有効であることを確認します。

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/orchestration/stepMapping

デフォルトの URL：/api/sn_devops/devops/orchestration/stepMapping

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 31. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 32. クエリパラメーター
名前	説明
branchName	オーケストレーションタスクに関連付けられたブランチの名前。データタイプ：文字列
isMultiBranch	オーケストレーションツールが Jenkins の場合、プロジェクトがマルチブランチかどうかを示すフラグ。有効な値： true：プロジェクトはマルチブランチタイプです。 false：プロジェクトはマルチブランチタイプではありません。データタイプ：ブールデフォルト値：false
parentStageName	オーケストレーションタスクが親オーケストレーションタスク内にネストされた子である場合、親オーケストレーションタスクの名前。データタイプ：文字列
parentStageURL	オーケストレーションタスクが親オーケストレーションタスク内にネストされた子である場合、親オーケストレーションタスクの URL。データタイプ：文字列
orchestrationTaskName	必須です。オーケストレーションタスクの名前。データタイプ：文字列
orchestrationTaskURL	必須です。オーケストレーションタスクの URL。注: パーセント (%) エンコードする必要があります (例： https%3A%2F%2Fjenkins.mycompany.com%3A8080%2Fjob%2FMobile-Platform-deploy%2F)。データタイプ：文字列
testConnection	インスタンスと DevOps ツール間のエンドツーエンド接続をテストするかどうかを示すフラグ。有効な値： true：エンドツーエンド接続をテストします。 false：エンドツーエンド接続をテストしません。データタイプ：ブーリアンデフォルト値：false
toolId	必須です。オーケストレーションツールの sys_id。オーケストレーションツール [sn_devops_orchestration_tool] テーブルにあります。データタイプ：文字列
toolType	必須です。ツールのタイプ。有効な値：jenkins データタイプ：文字列

表 : 33. 要求本文パラメーター
名前	説明
なし

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 34. 要求ヘッダー
ヘッダー	説明
Accept	応答本文のデータフォーマット。application/json のみをサポートします。

表 : 35. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 36. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
401	権限がありません。ユーザー資格情報が間違っているか、渡されていません。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


要素	説明
status	検証が成功したかどうかを示すフラグです。有効な値： true:検証に成功しました。 false:検証に失敗しました。データタイプ：ブーリアン
stepValid	送信された情報が有効かどうかを示すフラグ。有効な値： true:送信された情報は有効です。 false:送信された情報が有効ではありません。データタイプ：ブーリアン

サンプル cURL 要求

curl -X GET "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/stepMapping?toolId=f0ca45679323008b52f3b457415ae6&orchestrationTaskName=Platform-Analytics-UAT-Deployment&orchestrationTaskURL=https%253A%252F%252Fjenkins.mycompany.com%253A8080%252Fjob%252FMobile-Platform-deploy%252F&toolType=jenkins "
 -H "Accept: application/json" \
 -u "username":"password"

情報が有効な場合の結果。

{
  "result": {
    "stepValid": true,
    "status": "Success"
  }
}

サンプル cURL 要求

curl -X GET "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/stepMapping?toolId=f0ca45679323008b52f3b457415ae6&orchestrationTaskName=Platform-Analytics-UAT-Deployment&orchestrationTaskURL=https%253A%252F%252Fjenkins.mycompany.com%253A8080%252Fjob%252FMobile-Platform-deploy%252F&toolType=jenkins "
 -H "Accept: application/json" \
 -u "username":"password"

情報が無効な場合の結果。

{
"result": {
  "stepValid": false,
  "status": "Success"
}

DevOps - GET /devops/plan/schema

特定の計画 (アプリ、バージョン、または作業アイテム) のスキーマオブジェクトを返します。

必要なスキーマオブジェクトを取得したら、それを使用して、対応する POST 呼び出しの要求本文を作成します (POST /plan/app、POST /plan/version、または POST /plan/workitem)。

注:

このエンドポイントは、必要な要求本文要素のみを返します。

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/plan/schema

デフォルトの URL：/api/sn_devops/devops/plan/schema

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 37. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 38. クエリパラメーター
名前	説明
resource	返されるリソーススキーマのタイプ。有効な値 (値の大文字と小文字を区別しない)： app version work_item データタイプ：文字列

表 : 39. 要求本文パラメーター
名前	説明
なし

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 40. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。

表 : 41. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 42. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
401	認証が無効か見つかりません。
404	見つかりません。指定されたレコードが見つかりませんでした。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


名前	説明
app	バージョンに関連付けられたアプリケーションの説明。データタイプ：オブジェクト `"app": { "createdDateTime": "String", "id": "String", "shortDescription": "String", "team": {Object}, "url": "String" }`
app.createdDateTime	ソース DevOps ツールでアプリケーションが作成された日時。データタイプ：文字列
app.id	アプリケーションの一意の識別子。ソース計画立案ツールによって生成されます。データタイプ：文字列
app.shortDescription	関連付けられたアプリケーションの簡単な説明。データタイプ：文字列
app.team	アプリケーションに関連付けられたチームの説明。データタイプ：オブジェクト `"team": { "id": "String", "name": "String" }`
app.team.id	アプリケーションに関連付けられたチームの一意の識別子。ソース計画立案ツールによって生成されます。データタイプ：文字列
app.team.name	アプリケーションに関連付けられたチームの名前。データタイプ：文字列
app.url	ソース計画立案ツールサイトのアプリケーションの URL。データタイプ：文字列
assignedTo	作業アイテムがアサインされているユーザーの説明。データタイプ：オブジェクト `"assignedTo": { "email": "String", "id": "String", "name": "String", "userName": "String" }`
assignedTo.email	作業アイテムにアサインされたユーザーのメールアドレス。データタイプ：文字列
assignedTo.id	作業アイテムにアサインされたユーザーの一意の識別子。データタイプ：文字列
assignedTo.name	作業アイテムにアサインされたユーザーの名前。データタイプ：文字列
assignedTo.userName	作業アイテムにアサインされたユーザーのユーザー名。データタイプ：文字列
createDateTime	アプリケーション、バージョン、または作業アイテムのレコードが作成された日時。データタイプ：文字列
id	アプリケーション、バージョン、または作業アイテムの一意の識別子。ソース計画立案ツールによって生成されます。データタイプ：文字列
name	アプリケーションの名前。データタイプ：文字列
path	アプリケーションへの相対パス。データタイプ：文字列
shortDescription	アプリケーション、バージョン、または作業アイテムの簡単な説明。データタイプ：文字列
state	作業アイテムのステータス。ソース計画立案ツールによって生成されます。データタイプ：文字列
team	アプリケーションに関連付けられたチームの説明。データタイプ：オブジェクト `"team": { "id": "String", "name": "String" }`
team.id	アプリケーションに関連付けられたチームの一意の識別子。ソース計画立案ツールによって生成されます。データタイプ：文字列
team.name	アプリケーションに関連付けられたチームの名前。データタイプ：文字列
type	作業アイテムのタイプ。計画立案ツールによって生成されます。データタイプ：文字列
url	アプリケーション、バージョン、または作業アイテムにアクセスするために使用する URL。データタイプ：文字列
version	バージョンを記述するアレイ。データタイプ：オブジェクト `"version": { "app": {Object}, "createdDateTime": "String", "id": "String", "shortDescription": "String", "url": "String" }`
version.app	バージョンに関連付けられたアプリケーションの説明。データタイプ：オブジェクト `"app": { "createdDateTime": "String", "id": "String", "shortDescription": "String", "team": {Object}, "url": "String" }`
version.app.createdDateTime	ソース DevOps ツールでバージョンが作成された日時。データタイプ：文字列
version.app.id	アプリケーションの一意の識別子。ソース計画立案ツールによって生成されます。データタイプ：文字列
version.app.shortDescription	関連付けられたアプリケーションの簡単な説明。データタイプ：文字列
version.app.team	アプリケーションに関連付けられたチームの説明。データタイプ：オブジェクト `"team": { "id": "String", "name": "String" }`
version.app.team	アプリケーションに関連付けられたチームの一意の識別子。ソース計画立案ツールによって生成されます。データタイプ：文字列
version.app.team.id	アプリケーションに関連付けられたチームの名前。データタイプ：文字列
version.app.url	ソース計画立案ツールサイトのアプリケーションの URL。データタイプ：文字列
version.createdDateTime	ソース DevOps ツールでバージョンが作成された日時。データタイプ：文字列
version.id	バージョンの一意の識別子。ソース計画立案ツールによって生成されます。データタイプ：文字列
version.shortDescription	関連付けられたバージョンの簡単な説明。データタイプ：文字列
version.url	ソース計画立案ツールサイトのバージョンの URL。データタイプ：文字列

resource=app のサンプル cURL 要求

curl "https://instance.servicenow.com/api/sn_devops/v1/devops/plan/schema?resource=app" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": {
    "id": "PRODUCT1234",
    "shortDescription": "Mobile UI",
    "createdDateTime": "1970-01-01T08:15:30-05:00",
    "team": {
      "name": "Mobile UI",
      "id": "f0ca45679323008b52f3b457415ae6"
    },
    "url": "https://jira.com/mycompany/browse/PRODUCT-125"
  }
}

resource=version のサンプル cURL 要求

curl "https://instance.servicenow.com/api/sn_devops/v1/devops/plan/schema?resource=version" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": {
    "id": "REL1234",
    "shortDescription": "APIs Release",
    "createdDateTime": "1970-01-01T08:15:30-05:00",
    "app": {
      "id": "PRODUCT1234",
      "shortDescription": "Mobile UI",
      "createdDateTime": "1970-01-01T08:15:30-05:00",
      "team": {
        "name": "Mobile UI",
        "id": "f0ca45679323008b52f3b457415ae6"
      },
      "url": "https://jira.com/mycompany/browse/PRODUCT-125"
    },
    "url": "https://jira.com/mycompany/browse/REL-125"
  }
}

resource=work_item のサンプル cURL 要求

curl "https://instance.servicenow.com/api/sn_devops/v1/devops/plan/schema?resource=work_item" \
--request GET \
--header "Accept:application/json" \
--user "username":"password"

{
  "result": {
    "id": "STR1234",
    "type": "Story",
    "shortDescription": "Planning API Spec",
    "state": "In-progress",
    "createdDateTime": "1970-01-01T08:15:30-05:00",
    "assignedTo": {
      "name": "Leo Neo",
      "userName": "lenn",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "email": "lenn@smithworksinc.com"
    },
    "version": {
      "id": "REL1234",
      "shortDescription": "APIs Release",
      "createdDateTime": "1970-01-01T08:15:30-05:00",
      "app": {
        "id": "PRODUCT1234",
        "shortDescription": "Mobile UI",
        "createdDateTime": "1970-01-01T08:15:30-05:00",
        "team": {
          "name": "Mobile UI",
          "id": "f0ca45679323008b52f3b457415ae6"
        },
        "url": "https://jira.com/mycompany/browse/PRODUCT-125"
        },
        "url": "https://jira.com/mycompany/browse/REL-125"
    },
    "app": {
      "id": "PRODUCT1234",
      "shortDescription": "Mobile UI",
      "createdDateTime": "1970-01-01T08:15:30-05:00",
      "team": {
        "name": "Mobile UI",
        "id": "f0ca45679323008b52f3b457415ae6"
      },
      "url": "https://jira.com/mycompany/browse/PRODUCT-125"
    },
    "url": "https://jira.com/mycompany/browse/HALOKEY-25"
  }
}

DevOps - POST/devops/artifact/registration

アーティファクトを ServiceNow インスタンスに登録するオーケストレーションツールを有効にします。

このエンドポイントは、新しいアーティファクトとアーティファクトバージョンを作成し、それらをコミットに関連付けます。以下で、エンドポイントのプロセスフローについて説明します。

要求で toolId が渡されると、エンドポイントはツールがインスタンス内に存在することを検証します。また、artifacts.repositoryName で指定されたアーティファクトリポジトリが存在するかどうかを確認し、存在しない場合は、関連するアーティファクトツールの下に作成します。
要求で toolId が渡されない場合、リポジトリは作成されますが、アーティファクトツールにリンクされません。
その後、artifacts.name で指定されたアーティファクトが既に存在しているかどうかを確認し、存在しない場合は、関連するリポジトリの下に作成します。
artifact.version が要求で渡された場合：
- 存在しない場合は、関連するアーティファクトバージョン [sn_devops_artifact_version] テーブルに新しいアーティファクトバージョンレコードが作成されます。
- エンドポイントは、指定されたビルドの詳細 (pipelineName または projectName、taskExecutionNumber、branchName、および stageName) と orchestrationToolId パラメーターに基づいて、関連するタスク実行を検索します。
- タスク実行が検出され、その後処理が完了すると、アーティファクトバージョンがタスク実行にリンクされ、TaskExecution のアーティファクト [sn_devops_m2m_artifact_execution] テーブルに格納されます。これらのタスク実行にリンクされたコミットは、アーティファクトバージョンにも関連付けられ、コミットするアーティファクトバージョン [sn_devops_m2m_artifact_version_commit] テーブルに格納されます。アーティファクトを作成しなかった以前のタスク実行にリンクされているコミットも、そのアーティファクトバージョンに関連付けられます。
- タスク実行が検出され、その後処理が完了していない場合、要求はアーティファクトステージング済み要求 [sn_devops_artifact_staging] テーブルに保持されます。ステージング済み要求には、タスク実行への参照が含まれています。
- タスク実行が見つからない場合、要求はステージングテーブルに保持されます。ステージング済み要求には、ビルドの詳細が含まれています。
artifact.version が渡されない場合、ツール構成に応じて、アーティファクトツールが Webhook をサポートしている場合は /devops/tool/artifact エンドポイントを呼び出すことで、またはアーティファクトツールからアーティファクトバージョンを取得するカスタムサブフローを使用して、アーティファクトバージョンが取得されます。

アーティファクトの詳細については、「リリースでの DevOps 変更促進の使用」を参照してください。

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/artifact/registration

デフォルトの URL：/api/sn_devops/devops/artifact/registration

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 43. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 44. クエリパラメーター
名前	説明
orchestrationToolId	必須です。アーティファクトに関連付けられたオーケストレーションツールの sys_id。エンドポイントはこの情報を使用して、タスク実行情報を特定します。データタイプ：文字列テーブル:オーケストレーションツール [sn_devops_orchestration_tool]
toolId	アーティファクトに関連付けられたアーティファクトツールの sys_id。データタイプ：文字列テーブル:アーティファクトツール [sn_devops_artifact_tool]

表 : 45. 要求本文パラメーター (XML または JSON)
名前	説明
artifacts	エントリが少なくとも 1 つ必要です。登録するアーティファクトバージョンを各オブジェクトが一意に識別するオブジェクトのアレイ。データタイプ：オブジェクトのアレイ `"artifacts": [ { "name": "String", "repositoryName": "String", "semanticVersion": "String", "version": "String" } ]`
artifacts.name	必須です。アーティファクトファイル名。データタイプ：文字列最大長：160 文字
artifacts.repositoryName	必須です。アーティファクトリポジトリ名。指定されたリポジトリレコードが存在しない場合は作成されます。データタイプ：文字列最大長：160 文字
artifacts.semanticVersion	アーティファクトのセマンティックバージョン。データタイプ：文字列形式：MAJOR.MINOR.PATCH 可能な値の例： 2.0.0 2.0.0-rc.2 2.0.0-rc.1 1.0.0-beta 最大長：160 文字デフォルト：Null
artifacts.version	toolId が渡されない場合は必須です。アーティファクトバージョンデータタイプ：文字列形式：MAJOR.MINOR 最大長：160 文字デフォルト：Null
branchName	複数分岐プロジェクトの場合は必須です。アーティファクトが保存されているリポジトリ内の分岐の名前。データタイプ：文字列最大長：160 デフォルト：Null
pipelineName	projectName が渡されない場合は必須です。パイプライン名。データタイプ：文字列最大長：160 デフォルト：Null
projectName	pipelineName が渡されない場合は必須です。自由形式のプロジェクト名。データタイプ：文字列最大長：160 デフォルト：Null
stageName	pipelineName が渡されない場合は必須です。ステージ名。データタイプ：文字列最大長：160 デフォルト：Null

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 46. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。
認証	v2 以降、この API はトークンベースの認証をサポートしています。トークンは、ツール [sn_devops_tool] テーブルにあるツールレコードの [ トークンのコピー ] ボタンをクリックして取得できます。トークンは、Authorization: の形式で認証ヘッダーで使用できます `sn_devops。DevOpsToken <tool_sys_id>:<tool_token>`。注: 基本認証の詳細 (ユーザー名とパスワード) がトークン付きの認証ヘッダーに加えて指定されている場合、基本認証が優先されます。 devops.systemユーザーがインスタンスで利用できない場合は、[トークンベースの認証が成功した後にこのユーザーに切り替え] プロパティを使用します。このプロパティを使用すると、トークン認証を完了するために必要な sn_devops.integration ロールを持つユーザーを設定できます。詳細については、「DevOps Change Velocity properties」を参照してください。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 47. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 48. ステータスコード
ステータスコード	説明
200	成功です。応答本文ありで成功しました。
201	作成されました。応答本文ありで成功しました。
400	要求が正しくありません。要求 URI がシステム内の API と一致しないか、不明な理由で操作が失敗しました。無効なヘッダーによっても、このエラーが発生する場合があります。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


名前	説明
response	アーティファクト登録要求の結果。データタイプ：オブジェクト `"response": { "artifact": {Object}, "artifact_register_requests": {Object}, "artifact_repository": {Object}, "artifact_version": {Object} }`
response.artifact	処理された各アーティファクトの結果。データタイプ：オブジェクト `"artifact": { "create": [Array], "found": [Array], "update": [Array] }`
response.artifact.create	要求によってアーティファクトレコードが作成された場合は、作成されたレコードのsys_idsのリスト。データタイプ：オブジェクトのアレイ `"create": [ { "id": "String" } ]` テーブル:アーティファクト [sn_devops_artifact]
response.artifact.create.id	要求によって作成されたアーティファクトレコードの sys_id。データタイプ：文字列
response.artifact.found	アーティファクトが既にアーティファクトテーブルに存在する場合、既存のアーティファクトレコードの sys_id のリスト。注: 既存のパッケージは変更されません。データタイプ：オブジェクトのアレイ `"found": [ { "id": "String" } ]`
response.artifact.found.id	既存のアーティファクトレコードの sys_id。データタイプ：文字列
response.artifact.update	現在、使用されていません。
response.artifact.update.id	現在、使用されていません。
response.artifact_register_requests	処理が完了せず、アーティファクトステージング済み要求テーブルに格納されているアーティファクト登録要求の結果。データタイプ：オブジェクト `"artifact_register_requests": { "create": [Array], "found": [Array], "update": [Array] }`
response.artifact_register_requests.create	要求でアーティファクトステージングレコードが作成された場合は、作成されたレコードの sys_id のリスト。データタイプ：オブジェクトのアレイ `"create": [ { "id": "String" } ]`
response.artifact_register_requests.create.id	要求によって作成されたアーティファクトステージングレコードの sys_id。データタイプ：文字列
response.artifact_register_requests.found	関連するアーティファクトステージングレコードがアーティファクトにある場合は、既存のアーティファクトステージングレコードの sys_id のリスト。注: 既存のパッケージは変更されません。データタイプ：オブジェクトのアレイ `"found": [ { "id": "String" } ]`
response.artifact_register_requests.found.id	既存のアーティファクトステージングレコードの sys_id。データタイプ：文字列
response.artifact_register_requests.update	現在、使用されていません。
response.artifact_register_requests.update.id	現在、使用されていません。
response.artifact_repository	要求の処理中に操作されたアーティファクトリポジトリレコードの結果。データタイプ：オブジェクト `"artifact_repository": { "create": [Array], "found": [Array], "update": [Array] }`
response.artifact_repository.create	要求によってアーティファクトリポジトリが作成された場合は、作成されたレコードの sys_id のリスト。データタイプ：オブジェクトのアレイ `"create": [ { "id": "String" } ]`
response.artifact_repository.create.id	要求によって作成されたアーティファクトリポジトリレコードの sys_id。データタイプ：文字列
response.artifact_repository.found	登録要求で使用されるアーティファクトリポジトリレコードが既に存在する場合、既存のレコードの sys_id のリスト。注: 既存のパッケージは変更されません。データタイプ：オブジェクトのアレイ `"found": [ { "id": "String" } ]`
response.artifact_repository.found.id	要求によって使用された既存のアーティファクトリポジトリレコードの sys_id。データタイプ：文字列
response.artifact_repository.update	エンドポイントがリポジトリの追跡フラグを (false から) true に更新した場合、変更されたリポジトリレコードの sys_id のリスト。データタイプ：オブジェクトのアレイ `"update": [ { "id": "String" } ]`
response.artifact_repository.update.id	追跡フラグが変更されたリポジトリレコードの sys_id。データタイプ：文字列
response.artifact_version	要求の処理中に操作されたアーティファクトバージョンレコードの結果。データタイプ：オブジェクト `"artifact_version": { "create": [Array], "found": [Array], "update": [Array] }`
response.artifact_version.create	要求の処理中に作成されたアーティファクトバージョンレコードの結果。データタイプ：オブジェクトのアレイ `"create": [ { "id": "String" } ]`
response.artifact_version.create.id	要求によって作成されたアーティファクトバージョンレコードの sys_id。データタイプ：文字列
response.artifact_version.found	登録要求で使用されるアーティファクトバージョンレコードが既に存在する場合、既存のレコードの sys_id のリスト。データタイプ：オブジェクトのアレイ `"found": [ { "id": "String" } ]`
response.artifact_version. found.id	要求によって使用された既存のアーティファクトバージョンレコードの sys_id。データタイプ：文字列
response.artifact_version.update	現在、使用されていません。
response.artifact_version.update.id	現在、使用されていません。
status	登録要求のステータス。可能な値：成功：応答本文に返される結果が含まれています。エラー：応答本文にすべてのエラーのリストが含まれています。データタイプ：文字列

サンプル cURL 要求

curl -X POST \
'https://instance.servicenow.com/api/sn_devops/devops/artifact/registration?toolId=391b4ff6dba24010bc8cdd384b96198f&orchestrationToolId=99d70b36dba24010bc8cdd384b961985' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-u 'username':'password' \
-d ' {"artifacts": [\
 {\
 "name": "sa-web.jar",\
 "version": "3.1",\
 "semanticVersion": "3.1.0",\
 "repositoryName": "services-1031"\
 },\
 {\
 "name": "sa-frontend.jar",\
 "version": "3.2",\
 "semanticVersion": "3.2.0",\
 "repositoryName": "services-1031"\
 }\
 ],\
 "pipelineName": "spring-boot-app",\
 "taskExecutionNumber": "160",\
 "stageName": "Build",\
 "branchName": "primary"\
}]'

{
"result": {
  "status": "Success",
  "response": {
    "artifact_repository": {
      "create": [
        {
          "id": "2e50ba8bdbaa4010bc8cdd384b961988"
        }
      ],
      "update": [],
      "found": [
        {
          "id": "2e50ba8bdbaa4010bc8cdd384b961988"
        }
      ]
    },
    "artifact": {
      "create": [
        {
          "id": "6a50f603dbea4010bc8cdd384b96193d"
        },
        {
          "id": "2e50f603dbea4010bc8cdd384b96193f"
        }
      ],
      "update": [],
      "found": []
    },
    "artifact_version": {
      "create": [
        {
          "id": "a650f603dbea4010bc8cdd384b96193e"
        },
        {
          "id": "6250f603dbea4010bc8cdd384b961940"
        }
      ],
      "update": [],
      "found": []
    },
    "artifact_register_requests": {
      "create": [
        {
          "id": "6250f603dbea4010bc8cdd384b96193f"
        },
        {
          "id": "6650f603dbea4010bc8cdd384b961940"
        }
      ],
      "update": [],
      "found": []
    }
  }
 }
}

DevOps - POST /devops/onboarding/app

DevOps サービスによって非同期に処理されるオンボーディングアプリイベントを作成します。

このエンドポイントは次のアクションを実行できます。

アプリケーションを作成します。
計画、リポジトリ、パイプラインなどの DevOps オブジェクトをアプリケーションに関連付けます。
変更ステップレコードを作成し、変更承認プロセスをパイプラインに関連付けます。

これらのアクションはすべてツールと機能に固有です。次の表は、サポートされている各ツールで利用可能なアクションの概要です。

アプリケーションオンボーディングマトリクス

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/onboarding/app

デフォルトの URL：/api/sn_devops/devops/onboarding/app

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 49. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 50. クエリパラメーター
名前	説明
なし

表 : 51. 要求本文パラメーター
名前	説明
apps	関連する ServiceNow インスタンス内に作成するアプリを定義するオブジェクトのアレイ。データタイプ：アレイ `"apps": [{ "bussinessApp": "String", "name": "String" }]`
apps.bussinessApp	アプリケーションのマップ先の cmdb_ci_business_app の名前。これにより、DevOps アプリケーションが指定された CMDB アプリケーションに関連付けられます。データタイプ：文字列
apps.name	必須です。作成するアプリケーションの分かりやすい名前。アプリは、計画、リポジトリ、およびパイプラインを結び付ける DevOps 製品コンテナーオブジェクトです。データタイプ：文字列
credentials	必須です。Webhook の作成に使用する資格情報。作成された Webhook は、通知を送信するためにツールで使用されます。データタイプ：オブジェクト `"credentials": { "name": "String", "password": "String" }`
credentials.name	必須です。エンドポイント要求を行うユーザーの ServiceNow ユーザー ID。このユーザーには devops.integration.user ロールが必要です。バージョン 1.34.1 以降、このユーザーには sn_devops.admin ロールが必要です。データタイプ：文字列テーブル：ユーザー [sys_user]
credentials.password	必須です。credenitals.name パラメーターで指定されたユーザーのパスワード。データタイプ：文字列
パイプライン	アプリケーションに関連付けるパイプラインのリスト。データタイプ：オブジェクトのアレイ `"pipelines": [{ "app": "String", "name": "String", "tool": "String" }]`
pipelines.app	pipelines オブジェクトが指定されている場合は必須です。pipelines.name パラメーターで指定された計画に関連付けるアプリケーションの名前。アプリケーションは既に作成されているか、この要求の apps オブジェクトで指定されている必要があります。データタイプ：文字列
pipelines.changeSteps	[ pipelines.name ] フィールドに指定されたパイプラインに対して作成する変更手順。データタイプ：オブジェクトのアレイ `"changeSteps": [{ "changeApprovalGroup": "String", "changeControlledBranches": "String", "changeType": "String", "name": "String", "type": "String" }]`
pipelines.changeSteps.changeApprovalGroup	changeSteps オブジェクトが指定されている場合は必須です。パイプラインに関連付ける変更承認グループの名前。このグループは ServiceNow インスタンスに既に存在している必要があります。データタイプ：文字列テーブル： Group [sys_user_group]
pipelines.changeSteps.changeControlledBranches	変更管理下にあるコード分岐のカンマ区切りリスト。これは複数分岐のサポートにのみ適用されます。データタイプ：文字列デフォルト：* (すべての分岐)
pipelines.changeSteps.changeType	changeSteps オブジェクトが指定されている場合は必須です。作成する変更要求のタイプ。データタイプ：文字列テーブル:変更要求 [change_request] テーブルの [タイプ] フィールド。
pipelines.changeSteps.name	changeSteps オブジェクトが指定されている場合は必須です。作成するステップの名前。ステップ名は、オーケストレーションツールのパイプライン内の対応するステップの名前と一致する必要があります。データタイプ：文字列
pipelines.changeSteps.type	changeSteps オブジェクトが指定されている場合は必須です。作成するステップのタイプ。データタイプ：文字列テーブル:ステップ [sn_devops_step] テーブルの [タイプ] フィールド。
pipelines.name	pipelines オブジェクトが指定されている場合は必須です。pipelines.app パラメーターで指定されたアプリケーションに関連付けるパイプラインの名前。このパイプラインは ServiceNow インスタンスで既に検出されている必要があります。データタイプ：文字列
pipelines.tool	pipelines オブジェクトが指定されている場合は必須です。パイプラインに関連付けて、一意のパイプライン/ツール識別子を作成するツール。データタイプ：文字列
plans	アプリケーションに関連付ける計画のリスト。データタイプ：オブジェクトのアレイ `"plans": [{ "app": "String", "name": "String", "tool": "String" }]`
plans.apps	plans オブジェクトが指定されている場合は必須です。plans.name パラメーターで指定された計画に関連付けるアプリケーションの名前。これらのアプリケーションは既に作成されているか、この要求の apps オブジェクトで指定される必要があります。データタイプ：文字列のアレイ
plans.name	plans オブジェクトが指定されている場合は必須です。plans.app パラメーターで指定されたアプリケーションに関連付ける計画の名前。この計画は ServiceNow インスタンスで既に検出されている必要があります。データタイプ：文字列
plans.tool	plans オブジェクトが指定されている場合は必須です。計画に関連付けて、一意の計画/ツール識別子を作成するツール。データタイプ：文字列
リポジトリ	アプリケーションに関連付けられたリポジトリのリスト。リポジトリオブジェクトにアプリパラメーターが含まれている場合は、リポジトリをアプリケーションにマッピングします。データタイプ：オブジェクトのアレイ `"repositories": [{ "app": "String", "name": "String", "tool": "String" }]`
repositories.app	repositories オブジェクトが指定されている場合は必須です。このリポジトリに関連付けるアプリケーションの名前。アプリケーションは既に作成されているか、この要求の apps オブジェクトで指定されている必要があります。データタイプ：文字列
repositories.name	repositories オブジェクトが指定されている場合は必須です。repositories.app パラメーターで指定されたアプリケーションに関連付けるリポジトリの名前。このリポジトリは ServiceNow インスタンスで既に検出されている必要があります。データタイプ：文字列
repositories.tool	repositories オブジェクトが指定されている場合は必須です。一意のリポジトリ/ツール識別子を作成するためにリポジトリに関連付ける分かりやすいツール名。ツールは ServiceNow インスタンスで既に作成されている必要があります。データタイプ：文字列
artifactRepositories.app	`artifactRepositories` オブジェクトが指定されている場合は必須です。この artifactRepositories に関連付けるアプリケーションの名前。アプリケーションが既に作成されているか、この要求の `apps` オブジェクトで指定されている必要があります。データタイプ：文字列
artifactRepositories.name	`artifactRepositories` オブジェクトが指定されている場合は必須です。artifactRepositories.appパラメーターで指定されたアプリケーションに関連付ける artifactRepositories の名前。この artifactRepositories は、ServiceNow インスタンスで既に検出されている必要があります。データタイプ：文字列
artifactRepositories.tool	`artifactRepositories` オブジェクトが指定されている場合は必須です。一意の artifactRepositories /tool 識別子を作成するために artifactRepositories に関連付ける、分かりやすいツール名。ツールは、ServiceNow インスタンスで既に作成されている必要があります。データタイプ：文字列

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 52. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 53. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 54. ステータスコード
ステータスコード	説明
202	オンボーディング要求が正常に作成されました。

応答本文のパラメーター


名前	説明
result	オンボーディング要求の結果。データタイプ：オブジェクト `"result": { "code": "String", "details": "String", "errors": {Object], "onboardingRequestID": "String", "status": "String" }`
result.code	HTTP ステータスコード。データタイプ：文字列
result.details	オンボーディング要求に関する詳細。データタイプ：文字列
result.errors	発生したエラーの説明。データタイプ：オブジェクト
result.error.message	エラーメッセージ。データタイプ：文字列
result.onboardingRequestID	オンボーディング要求の一意の識別子。/devops/onboarding/status エンドポイントを呼び出して、関連するオンボーディングプロセスのステータスを取得するときに、この値を使用します。データタイプ：文字列
result.status	オンボーディング要求のステータス (成功または失敗)。データタイプ：文字列

cURL 要求

この例では、Bike Rental Service アプリケーションを作成し、Jenkins パイプラインの Bike Rentals、GitHub リポジトリ nowDevops01/CorpSite、および Azure プラン testPlan_Bike_Rental に関連付けています。

curl -X POST "https://servicenow-instance/api/sn_devops/v1/devops/onboarding/app" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u "username":"password" \
-d "{
  "apps": [
    {
      "name": "Bike Rental Service"
    }
  ]
  "pipelines": [
    {
      "tool": "Primary Jenkins",
      "name": "Bike Rentals",
      "app": "Bike Rental Service",
      "changeSteps": [
        {
          "name": "Prod",
          "type": "deploy",
          "changeApprovalGroup": "Change Management",
          "changeType": "normal"
        }
      ]
    }
  ],
  "repositories": [
    {
      "tool": "Primary GitHub",
      "name": "nowDevops01/CorpSite",
      "app": "Bike Rental Service"
    }
  ]
  "plans": [
    {
      "tool": "Primary Azure",
      "name": "testPlan_Bike_Rental",
      "apps": [
        "Bike Rental Service"
      ]
    }
  ]
  "credentials" : {
    "name": "devops_user",
    "password": "devops_password"
  } 
}

{
  "result":{
    "status": "Success",
    "details": "Onboarding request has been created. Please use the /status api and the onboarding request number to get the status of the request",
    "onboardingRequestID": "IBE0001045",
    "code": "202"
  }
}

DevOps - POST /devops/onboarding/tool

DevOps サービスによって非同期に処理されるオンボーディングツールイベントを作成します。

要求がポストされたツールのタイプに応じて、エンドポイントは次のアクションを実行します。

関連する ServiceNow インスタンス内にツールを作成する
ツールに接続する
ツールの設定を試行する (接続に成功した場合のみ)
ツールを検出する (接続に成功した場合のみ)

これらのアクションはすべてツール固有であり、指定されたツールの統合機能に基づいて実行されます。

ツールオンボーディングマトリクス

このエンドポイントで返される結果は、要求がポストされたかどうかのみを示し、関連するツールが作成されたかどうかは示しません。実際のツールの作成は非同期に処理されます。ツールの作成と他のすべてのアクションのステータスを取得するには、/devops/onboarding/status エンドポイントを呼び出し、このエンドポイントによって返される onboardingRequestID パラメーターを渡す必要があります。

このエンドポイントにアクセスするには、管理者が、インスタンスでツールを設定するために DevOps 接続と資格情報エイリアス (CreateDevOpsTool) を設定する必要があります。詳細については、「 DevOps 変更速度管理のインストール」を参照してください。さらに、呼び出し元エンティティには devops.integration.user ロールが必要です。

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/onboarding/tool

デフォルトの URL：/api/sn_devops/devops/onboarding/tool

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 55. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 56. クエリパラメーター
名前	説明
なし

表 : 57. 要求本文パラメーター
名前	説明
credentials	必須です。Webhook の作成に使用する資格情報。作成された Webhook は、通知を送信するためにツールで使用されます。データタイプ：オブジェクト `"credentials": { "name": "String", "password": "String" }`
credentials.name	必須です。エンドポイント要求を行うユーザーの ServiceNow ID。このユーザーには devops.integration.user ロールが必要です。バージョン 1.34.1 以降、このユーザーには sn_devops.admin ロールが必要です。データタイプ：文字列テーブル：ユーザー [sys_user]
credentials.password	必須です。credenitals.name パラメーターで指定されたユーザーのパスワード。データタイプ：文字列
tools	必須。関連付けられた ServiceNow インスタンス内に作成するためのツール。1 つの要求で 1 つ以上のツールを作成できます。データタイプ：オブジェクトのアレイ `"tools": [{ "name": "String", "password": "String", "type": "String", "useMidServer": Boolean, "username": "String", "url": "String" }]`
tools.name	必須です。作成するツールの分かりやすい名前またはラベル。この名前は、DevOps サービスでツールを識別するために使用されます。データタイプ：文字列
tools.password	アジャイルツール以外で必須です。ツールへのアクセスに使用するパスワード。サポートされている認証は基本認証とトークン認証です。OAuth はサポートされていません。データタイプ：文字列
tools.type	必須です。作成するツールのタイプ (GitHub や BitBucket など)。指定された値は、ツール統合 [sn_devops_tool_integration] テーブルのツールラベルの 1 つである必要があります。データタイプ：文字列
tools.useMidServer	ツールが MID サーバーを介して接続するかどうかを示すフラグ。有効な値： true：MID サーバーを介して接続します。 false：MID サーバーを介して接続しません。データタイプ：ブーリアン
tools.username	アジャイルツール以外で必須です。このエンドポイントを介してツールにアクセスするために使用するユーザー名。データタイプ：文字列
tools.url	アジャイルツール以外で必須です。作成するツールの URL。DevOps サービスでは、この URL を使用してツールと統合します。データタイプ：文字列

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 58. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 59. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 60. ステータスコード
ステータスコード	説明
202	オンボーディング要求が正常に作成されました。

応答本文のパラメーター


名前	説明
result	オンボーディング要求の結果。データタイプ：オブジェクト `"result": { "code": "String", "details": "String", "errors": {Object}, "onboardingRequestID": "String", "status": "String" }`
result.code	HTTP ステータスコード。データタイプ：文字列
result.details	オンボーディング要求に関する詳細メッセージ。データタイプ：文字列
result.errors	発生したエラーの説明。データタイプ：オブジェクト
result.error.message	エラーメッセージ。データタイプ：文字列
result.onboardingRequestID	オンボーディング要求の一意の識別子。/devops/onboarding/status エンドポイントを呼び出して、関連するツールのオンボーディングプロセスのステータスを取得するときに、この値を使用します。データタイプ：文字列
result.status	オンボーディング要求のステータス (成功または失敗)。データタイプ：文字列

cURL 要求

次の例は、GitHub をオンボーディングする方法を示しています。

curl -X POST "https://servicenow-instance/api/sn_devops/v1/devops/onboarding/tool" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-u "username":"password" \
-d {
  "tool":[{
    "name": "Primary GitHub",
    "type": "GitHub",
    "url": "https"//api.github.com",
    "username": "username",
    "password": "password",
    "useMidServer": false 
  }]
  "credentials" : {
    "name": "devops_user",
    "password": "devops_password"
  }
}

{
  "result":{
    "status": "Success",
    "details": "Onboarding request has been created. Please use the /status api and the onboarding request number to get the status of the request",
    "onboardingRequestID": "IBE0001041",
    "code": "202"
  }
}

DevOps - POST /devops/orchestration/changeControl

変更管理下にあるオーケストレーションタスクの ServiceNow インスタンスでコールバックを登録します。変更要求で決定が行われたら、これを呼び出すことができます。

このエンドポイントを呼び出す前に、ServiceNow インスタンスにオーケストレーションタスクを作成しておく必要があります。このタスクは、Discovery を使用するか、DevOps - POST /devops/orchestration/stepMapping エンドポイントを呼び出すことで作成できます。また、オーケストレーションタスクが以前に定義されたパイプラインステップに関連付けられ、変更コントロールが有効になっていることを確認する必要もあります ([アプリステージ] フォームで [変更コントロール ] オプションを選択します)。詳細については、「 DevOps 変更の加速」を参照してください。

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/orchestration/changeControl

デフォルトの URL：/api/sn_devops/devops/orchestration/changeControl

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 61. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 62. クエリパラメーター
名前	説明
toolId	必須です。指定されたタスクを変更管理下に置く DevOps ツールの sys_id。データタイプ：文字列テーブル:オーケストレーションツール [sn_devops_orchestration_tool]
toolType	ツールのタイプ。有効な値：ツールを識別する任意の値 (「jenkins」など)。データタイプ：文字列

表 : 63. 要求本文パラメーター
名前	説明
callbackURL	必須です。関連する変更要求承認プロセスが完了したときに ServiceNow インスタンスがコールバックできる URL。このコールバックは、承認結果に基づいてパイプラインの実行を続行するか、または続行しません。データタイプ：文字列
changeRequestDetails	変更要求をクローズするときに設定するフィールドの名前と値のペア。このオブジェクトには、以下を除く変更要求レコードの任意のフィールドを含めることができます。影響 number risk risk_impact_analysis sys_id これらのフィールドが要求に含まれている場合、エンドポイントは 400 エラーを返し、変更要求は更新されません。また、他の必須フィールドの設定を必要とするフィールドを含めたが、それらのフィールドが送信されない場合は、パイプラインの後の処理で要求が失敗します。この失敗は、変更要求の作業メモに、その変更要求のエラーメッセージとともに記載されています。例：`変更の要求の更新が理由 <プラットフォームからのエラーメッセージ> で失敗しました。変更要求および関連するステップの実行をキャンセルしています。` このオブジェクトでブーリアンパラメーター setCloseCode を渡して、関連する変更要求レコードのクローズ情報を設定するかどうかを指定することもできます。 true に設定すると、close_code フィールドがジョブのステータスに設定され、close_notes フィールドが関連する変更要求レコードのステップ実行へのリンクに設定されます。デフォルト値は true です。 false に設定すると、close_code フィールドと close_notes フィールドは設定されず、ステップ実行へのリンクが work_notes フィールドに設定されます。データタイプ：オブジェクト
isMultiBranch	オーケストレーションツールが Jenkins の場合、プロジェクトがマルチブランチかどうかを示すフラグ。有効な値： true：プロジェクトはマルチブランチタイプです。 false：プロジェクトはマルチブランチタイプではありません。データタイプ：ブールデフォルト値：false
orchestrationTaskDetails	必須です。オーケストレーションタスクの説明。データタイプ：オブジェクト `"orchestrationTaskDetails": { "message": "String", "triggerType": "String", "upstreamTaskExecutionURL": "String" }`
orchestrationTaskDetails.message	自由形式のテキストメッセージ。データタイプ：文字列
orchestrationTaskDetails.triggerType	必須です。オーケストレーションタスクが開始された方法。有効な値： scm：Git/scm ツールのコードコミットによってジョブがトリガーされました。 upstream：アップストリームのジョブがこのジョブをトリガーしました。 user：ユーザーが手動でジョブを開始しました。データタイプ：文字列
orchestrationTaskDetails.upstreamTaskExecutionURL	triggerType が `upstream` に設定されている場合は必須です。アップストリームタスク実行 URL。例：https://jenkins.mycompany.com:8080/job/Mobile-Platform-test/40/ データタイプ：文字列
orchestrationTaskURL	必須です。コールバックを作成するオーケストレーションタスクの URL。例：https://jenkins.mycompany.com:8080/orchestration_task/Mobile-Platform-deploy/ データタイプ：文字列
parentNode	オーケストレーションタスクが親オーケストレーションタスク内にネストされた子である場合、この値には親ノードの詳細が含まれます。データタイプ：オブジェクト `"parentNode": { "id": "String", "name": "String", "upstreamStageName": "String", "upstreamTaskExecutionURL": "String" }`
parentNode.id	親ノードの一意の ID。 Jenkins では、この値はパイプラインステージ ID に対応します。データタイプ：文字列
parentNode.name	親ノードの名前。 Jenkins では、この値はパイプラインステージ名に対応します。データタイプ：文字列
parentNode.upstreamStageName	親ノードのアップストリームオーケストレーションタスクの名前。 Jenkins では、この値はパイプラインステージ名に対応します。データタイプ：文字列
parentNode.upstreamTaskExecutionURL	親ノードのアップストリームタスク実行の URL。 Jenkins では、この値はパイプラインステージ実行に対応します。データタイプ：文字列
parentStageName	オーケストレーションタスクが親オーケストレーションタスク内にネストされた子である場合、親オーケストレーションタスクの名前。データタイプ：文字列
parentStageURL	オーケストレーションタスクが親オーケストレーションタスク内にネストされた子である場合、親オーケストレーションタスクの URL。データタイプ：文字列

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 64. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。サポートされるタイプ：application/json または application/xml。デフォルト： application/json
認証	v2 以降、この API はトークンベースの認証をサポートしています。トークンは、ツール [sn_devops_tool] テーブルにあるツールレコードの [ トークンのコピー ] ボタンをクリックして取得できます。トークンは、Authorization: の形式で認証ヘッダーで使用できます `sn_devops。DevOpsToken <tool_sys_id>:<tool_token>`。注: 基本認証の詳細 (ユーザー名とパスワード) がトークン付きの認証ヘッダーに加えて指定されている場合、基本認証が優先されます。 devops.systemユーザーがインスタンスで利用できない場合は、[トークンベースの認証が成功した後にこのユーザーに切り替え] プロパティを使用します。このプロパティを使用すると、トークン認証を完了するために必要な sn_devops.integration ロールを持つユーザーを設定できます。詳細については、「DevOps Change Velocity properties」を参照してください。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 65. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 66. ステータスコード
ステータスコード	説明
201	要求が正常に完了しました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
401	認証が無効か見つかりません。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


名前	説明
changeControl	オーケストレーションタスクが変更管理下にあるかどうかを示すフラグ。可能な値： true：変更管理下にあります。 false：変更管理下にありません。データタイプ：ブーリアン

cURL 要求

curl -X POST "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/changeControl?toolId=f0ca45679323008b52f3b457415ae6&toolType=jenkins"
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{
  \"orchestrationTaskURL\":\"https://jenkins.mycompany.com:8080/orchestration task/Mobile-Platform-deploy/\",
  \"callbackURL\":\"https://jenkins.mycompany.com:8080/sn-devops/964aca59-0cae-4d9b-a36d-5929f426cf31\",
  \"orchestrationTaskDetails\":{
    \"message\":\"Started by upstream project \\\"Mobile-Platform-test\\\" build number 40\",
    \"triggerType\":\"upstream\",
    \"upstreamTaskExecutionURL\":\"https://jenkins.mycompany.com:8080/job/Mobile-Platform-test/40/\"}
}"

応答本文。

{
"result": {
   "changeControl": true,
   "status": "Success"
   }
}

cURL 要求

この例では、変更要求をクローズするときに changeRequestDetails オブジェクトのフィールドを渡す方法を示します。

curl -X POST "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/changeControl?toolId=f0ca45679323008b52f3b457415ae6&toolType=jenkins"
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{
  "callbackURL":"http://192.168.0.4:3000/jenkins/sn-devops/pipeline_839b7605-b98d-4831-bc87-96829de7da37",
  "orchestrationTaskURL":"http://192.168.0.4:3000/jenkins/job/java_sample_tests#deploy/",
  "isMultiBranch":"false",
  "orchestrationTaskName":"java_sample_tests#deploy",
  "orchestrationTaskDetails":{
    "triggerType":"upstream",
    "upstreamTaskExecutionURL":"http://192.168.0.4:3000/jenkins/job/java_sample_tests/129/execution/node/35/wfapi/describe",
    "taskExecutionURL":"http://192.168.0.4:3000/jenkins/job/java_sample_tests/129/execution/node/50/wfapi/describe"
  },
  "changeRequestDetails":{
    "setCloseCode":false,
    "attributes":{
      "sys_created_by":"1832fbe1d701120035ae23c7ce610369",
      "sys_updated_by":"56826bf03710200044e0bfc8bcbe5dca",
      "requested_by":{
         "name":"test user1"
      },
      "watch_list":[
        {
          "name":"test user1"
        },
        {
          "name":"test user2"
        },
        {
          "name":"Alejandra Prenatt"
        },
          "56826bf03710200044e0bfc8bcbe5dca"
      ],
      "work_notes_list":[
        "56826bf03710200044e0bfc8bcbe5dca",
        "46c6f9efa9fe198101ddf5eed9adf6e7",
        "d8f57f140b20220050192f15d6673a98"
      ],
      "assigned_to":"1832fbe1d701120035ae23c7ce610369",
      "category":"Service",
      "sys_created_on":"2021-02-09 18:58:41",
      "priority":"2",
    }
  }
}"

応答本文。

{
"result": {
   "changeControl": true,
   "status": "Success"
   }
}

DevOps - POST /devops/orchestration/stepMapping

渡される情報がオーケストレーションタスクの作成に有効であり、以前に作成されたステップへの関連付けに有効であることを確認します。両方が有効な場合、オーケストレーションタスクが作成され、関連付けが行われます。

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/orchestration/stepMapping

デフォルトの URL：/api/sn_devops/devops/orchestration/stepMapping

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 67. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 68. クエリパラメーター
名前	説明
toolId	必須です。オーケストレーションツールの sys_id。オーケストレーションツール [sn_devops_orchestration_tool] テーブルにあります。データタイプ：文字列
toolType	必須です。ツールのタイプ。有効な値：jenkins データタイプ：文字列

表 : 69. 要求本文パラメーター
名前	説明
branchName	オーケストレーションタスクに関連付けられたブランチの名前。データタイプ：文字列
isMultiBranch	オーケストレーションツールが Jenkins の場合、プロジェクトがマルチブランチかどうかを示すフラグ。有効な値： true：プロジェクトはマルチブランチタイプです。 false：プロジェクトはマルチブランチタイプではありません。データタイプ：ブールデフォルト値：false
parentNode	オーケストレーションタスクが親オーケストレーションタスク内にネストされた子である場合、この値には親ノードの詳細が含まれます。データタイプ：オブジェクト `"parentNode": { "id": "String", "name": "String", "upstreamStageName": "String", "upstreamTaskExecutionURL": "String" }`
parentNode.id	親ノードの一意の ID。 Jenkins では、この値はパイプラインステージ ID に対応します。データタイプ：文字列
parentNode.name	親ノードの名前。 Jenkins では、この値はパイプラインステージ名に対応します。データタイプ：文字列
parentNode.upstreamStageName	親ノードのアップストリームオーケストレーションタスクの名前。 Jenkins では、この値はパイプラインステージ名に対応します。データタイプ：文字列
parentNode.upstreamTaskExecutionURL	親ノードのアップストリームタスク実行の URL。 Jenkins では、この値はパイプラインステージ実行に対応します。データタイプ：文字列
parentStageName	オーケストレーションタスクが親オーケストレーションタスク内にネストされた子である場合、親オーケストレーションタスクの名前。データタイプ：文字列
parentStageURL	オーケストレーションタスクが親オーケストレーションタスク内にネストされた子である場合、親オーケストレーションタスクの URL。データタイプ：文字列
orchestrationTaskName	必須です。オーケストレーションタスクの名前。これは、 orchestrationTaskURL で参照されているものと同じタスクです。データタイプ：文字列
orchestrationTaskURL	必須です。オーケストレーションタスクの URL。例：https://jenkins.mycompany.com:8080/orchestration_task/Mobile-Platform-deploy/ データタイプ：文字列

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 70. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。
認証	v2 以降、この API はトークンベースの認証をサポートしています。トークンは、ツール [sn_devops_tool] テーブルにあるツールレコードの [ トークンのコピー ] ボタンをクリックして取得できます。トークンは、Authorization: の形式で認証ヘッダーで使用できます `sn_devops。DevOpsToken <tool_sys_id>:<tool_token>`。注: 基本認証の詳細 (ユーザー名とパスワード) がトークン付きの認証ヘッダーに加えて指定されている場合、基本認証が優先されます。 devops.systemユーザーがインスタンスで利用できない場合は、[トークンベースの認証が成功した後にこのユーザーに切り替え] プロパティを使用します。このプロパティを使用すると、トークン認証を完了するために必要な sn_devops.integration ロールを持つユーザーを設定できます。詳細については、「DevOps Change Velocity properties」を参照してください。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 71. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 72. ステータスコード
ステータスコード	説明
201	成功。要求が正常に処理されました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
401	権限がありません。ユーザー資格情報が間違っているか、渡されていません。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


要素	説明
status	検証が成功したかどうかを示すフラグです。有効な値： true:検証に成功しました。 false:検証に失敗しました。データタイプ：ブーリアン
stepValid	送信された情報が有効かどうかを示すフラグ。有効な値： true:送信された情報は有効です。 false:送信された情報が有効ではありません。データタイプ：ブーリアン

サンプル cURL 要求

curl -X POST "https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/stepMapping?toolId=f0ca45679323008b52f3b457415ae6&toolType=jenkins"
-H "Accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{
  \"orchestrationTaskURL\":\" http://127.0.0.1:8090/jenkins/job/CorpSite/job/primary#deploy PROD/\",
  \"orchestrationTaskName\":\" primary#deploy PROD\"
}"

情報が有効な場合の結果。

{
  "result": {
    "stepValid": true,
    "status": "Success"
  }
}

情報が無効な場合の結果。

{
  "result": {
    "stepValid": false,
    "status": "Success"
  }
}

DevOps - POST /devops/package/registration

指定されたアーティファクトバージョンを含む新しいアーティファクトパッケージを作成するオーケストレーションツールを有効にします。

アーティファクトパッケージは、変更要求を表示するときに変更承認者にコミットを表示するために使用されます。変更要求にコミットを表示するには、変更承認を含むステージの前のステージでパッケージを作成する必要があります。

パッケージ登録要求に含まれるすべてのアーティファクトバージョンは、既に DevOps に登録されている必要があります。アーティファクトバージョンの登録の詳細については、「DevOps - POST/devops/artifact/registration」を参照してください。

通常は、パッケージに含めるアーティファクトのバージョンを識別するときに、artifacts.version および artifacts.name パラメーターを渡します。このエンドポイントの高度な機能を使用すると、バージョン自体の代わりに、各アーティファクトバージョンのビルドの詳細を渡すことができます。アーティファクト固有のビルドの詳細には、次のパラメーターが含まれます。

artifacts.pipelineName または artifacts.projectName
artifacts.taskExecutionNumber
artifacts.stageName
artifacts.branchName

エンドポイントは、これらのアーティファクト固有のビルドの詳細を使用してタスク実行情報を検索し、関連するバージョンをパッケージにコピーします。アーティファクト固有でないビルドの詳細 (pipelineName または projectName、taskExecutionNumber、branchName、および stageName) を使用して、作成されたパッケージをパイプライン実行に関連付けます。

注:

このエンドポイントは更新をサポートしていません。同じ名前のパッケージが既に存在する場合でも、常に新しいパッケージが作成されます。

アーティファクトパッケージの詳細については、「リリースでの DevOps 変更促進の使用」を参照してください。

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/package/registration

デフォルトの URL：/api/sn_devops/devops/package/registration

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 73. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 74. クエリパラメーター
名前	説明
orchestrationToolId	必須です。アーティファクトパッケージに関連付けられたオーケストレーションツールの sys_id。エンドポイントはこの情報を使用して、タスク実行情報を特定します。データタイプ：文字列テーブル:オーケストレーションツール [sn_devops_orchestration_tool]
toolId	アーティファクトパッケージに関連付けられたアーティファクトツールの sys_id。データタイプ：文字列テーブル:アーティファクトツール [sn_devops_artifact_tool]

表 : 75. 要求本文パラメーター
名前	説明
artifacts	エントリが少なくとも 1 つ必要です。パッケージに含めるアーティファクトバージョンを各オブジェクトが一意に識別するオブジェクトのアレイ。データタイプ：オブジェクトのアレイ `"artifacts": [ { "branchName": "String", "name": "String", "pipelineName": "String", "projectName": "String", "repositoryName": "String", "stageName": "String", "taskExecutionNumber": "String", "version": "String" ]`
artifacts.branchName	artifact.version が渡されず、複数分岐セットアップの場合は必須です。アーティファクトのバージョンが保存される分岐の名前。データタイプ：文字列最大長：160 デフォルト：Null
artifacts.name	必須です。アーティファクトファイル名。データタイプ：文字列最大長：160 文字
artifacts.pipelineName	artifact.version および artifacts.projectName が渡されない場合は必須です。パイプライン名。データタイプ：文字列最大長：160 デフォルト：Null
artifacts.projectName	artifact.version および artifact.pipelineName が渡されない場合は必須です。自由形式のプロジェクト名。データタイプ：文字列最大長：160 デフォルト：Null
artifacts.repositoryName	必須です。アーティファクトリポジトリ名。データタイプ：文字列最大長：160 文字
artifacts.stageName	artifact.version が渡されない場合は必須です。ステージ名。データタイプ：文字列最大長：160 デフォルト：Null
artifacts.taskExecutionNumber	artifact.version が渡されない場合は必須です。パイプライン実行番号。データタイプ：文字列デフォルト：Null
artifacts.version	ビルドの詳細が指定されていない場合は必須です。アーティファクトのバージョン。データタイプ：文字列形式：<Major>.<Minor> デフォルト：Null
branchName	複数分岐プロジェクトの場合は必須です。アーティファクトが保存されているリポジトリ内の分岐の名前。データタイプ：文字列最大長：200 文字デフォルト：Null
name	必須です。パッケージの名前。データタイプ：文字列最大長：160 文字
pipelineName	projectName が渡されない場合は必須です。パイプライン名。データタイプ：文字列最大長：160 文字デフォルト：Null
projectName	pipelineName が渡されない場合は必須です。自由形式のプロジェクト名。データタイプ：文字列最大長：160 デフォルト：Null
stageName	pipelineName が渡されない場合は必須です。ステージ名。データタイプ：文字列最大長：160 文字デフォルト：Null
taskExecutionNumber	必須です。パイプライン実行番号。データタイプ：文字列最大長：128 文字デフォルト：Null

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 76. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。
認証	v2 以降、この API はトークンベースの認証をサポートしています。トークンは、ツール [sn_devops_tool] テーブルにあるツールレコードの [ トークンのコピー ] ボタンをクリックして取得できます。トークンは、Authorization: の形式で認証ヘッダーで使用できます `sn_devops。DevOpsToken <tool_sys_id>:<tool_token>`。注: 基本認証の詳細 (ユーザー名とパスワード) がトークン付きの認証ヘッダーに加えて指定されている場合、基本認証が優先されます。 devops.systemユーザーがインスタンスで利用できない場合は、[トークンベースの認証が成功した後にこのユーザーに切り替え] プロパティを使用します。このプロパティを使用すると、トークン認証を完了するために必要な sn_devops.integration ロールを持つユーザーを設定できます。詳細については、「DevOps Change Velocity properties」を参照してください。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 77. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 78. ステータスコード
ステータスコード	説明
200	成功です。応答本文ありで成功しました。
201	作成されました。応答本文ありで成功しました。
400	要求が正しくありません。要求 URI がシステム内の API と一致しないか、不明な理由で操作が失敗しました。無効なヘッダーによっても、このエラーが発生する場合があります。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


名前	説明
response	パッケージ登録要求の結果。データタイプ：オブジェクト `"response": { "artifact_register_requests": {Object}, "sn_devops_m2m_artifact_version_package": {Object}, "sn_devops_package": {Object} }`
response.artifact_register_requests	処理が完了せず、アーティファクトステージング済み要求 [sn_devops_artifact_staging] テーブルに格納されている登録要求の結果。データタイプ：オブジェクト `"artifact_register_requests": { "create": [Array], "found": [Array], "update": [Array] }`
response.artifact_register_requests.create	要求でパッケージステージングレコードが作成された場合は、作成されたステージングレコードの sys_id のリスト。データタイプ：オブジェクトのアレイ `"create": [ { "id": "String" } ]`
response.artifact_register_requests.create.id	要求によって作成されたパッケージステージングレコードの sys_id。データタイプ：文字列
response.artifact_register_requests.found	関連するパッケージステージングレコードが既に存在する場合、既存のレコードの sys_id のリスト。注: 既存のパッケージは変更されません。データタイプ：オブジェクトのアレイ `"found": [ { "id": "String" } ]`
response.artifact_register_requests.found.id	既存のパッケージステージングレコードの sys_id。データタイプ：文字列
response.artifact_register_requests.update	現在、使用されていません。
response.artifact_register_requests.update.id	現在、使用されていません。
response.sn_devops_m2m_artifact_version_package	パッケージに関連付けられた各アーティファクトバージョンの結果。データタイプ：オブジェクト `"sn_devops_m2m_artifact_version_package": { "create": [Array], "found": [Array], "update": [Array] }`
response.sn_devops_m2m_artifact_version_package.create	要求によってアーティファクトバージョンをパッケージにリンクするレコードが作成された場合は、作成されたレコードのsys_idsのリスト。データタイプ：オブジェクトのアレイ `"create": [ { "id": "String" } ]` テーブル:パッケージ化するアーティファクトバージョン [sn_devops_m2m_artifact_version_package]
response.sn_devops_m2m_artifact_version_package.create.id	要求によって作成されたパッケージ化するアーティファクトバージョンレコードの sys_id。データタイプ：文字列
response.sn_devops_m2m_artifact_version_package.found	パッケージ化するアーティファクトバージョンテーブルにリンクレコードが既に存在する場合は、既存のリンクレコードの sys_id リスト。注: 既存のレコードは変更されません。データタイプ：オブジェクトのアレイ `"found": [ { "id": "String" } ]`
response.sn_devops_m2m_artifact_version_package.found.id	パッケージ化する既存のアーティファクトバージョンレコードの sys_id。データタイプ：文字列
response.sn_devops_m2m_artifact_version_package.update	現在、使用されていません。
response.sn_devops_m2m_artifact_version_package.update.id	現在、使用されていません。
response.sn_devops_package	要求の処理中に操作されたパッケージ [sn_devops_package] テーブル内のパッケージレコードの結果。データタイプ：オブジェクト `"sn_devops_package": { "create": [Array], "found": [Array], "update": [Array] }`
response.sn_devops_package.create	要求によってパッケージレコードが作成された場合は、作成されたレコードの sys_id のリスト。データタイプ：オブジェクトのアレイ `"create": [ { "id": "String" } ]`
response.sn_devops_package.create.id	要求によって作成されたパッケージレコードの sys_id。データタイプ：文字列
response.sn_devops_package.found	登録要求で使用されるパッケージレコードが既に存在する場合、既存のレコードの sys_id のリスト。注: 既存のレコードは変更されません。データタイプ：オブジェクトのアレイ `"found": [ { "id": "String" } ]`
response.sn_devops_package.found.id	要求によって参照される既存のパッケージレコードの sys_id。データタイプ：文字列
response.sn_devops_package.update	現在、使用されていません。
response.sn_devops_package.update.id	現在、使用されていません。
status	登録要求のステータス。可能な値：エラー：応答本文にすべてのエラーのリストが含まれています。成功：応答本文に返される結果が含まれています。データタイプ：文字列

サンプル cURL 要求

# Example passing the artifact version
curl -X POST "https://instance.servicenow.com/api/sn_devops/devops/package/registration?toolId=f0ca45679323008b52f3b457415ae6"\
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{\
"name": "sentimentpackage",\
"artifacts": [\
{\
"name": "sa-web.jar",\
"repositoryName": "services-1031",\
"version": "3.1"\
},\
{\
"name": "sa-frontend.jar",\
"repositoryName": "services-1031",\
"version": "9.2"\
}\
],\
"pipelineName": "spring-boot-app",\
"taskExecutionNumber": "160",\
"stageName": "Build",\
"branchName": "primary"\
}"

応答：パッケージが作成されました：

"result": {
"status": "Success",
"response": {
  "sn_devops_package": {
    "create": [
        {
          "id": "0d57367a532e00107109ddeeff7b122a"
        } 
      ],
    "update": [],
    "found": []
  },
  "sn_devops_m2m_artifact_version_package": {
    "create": [
      {
        "id": "c957367a532e00107109ddeeff7b122b"
      },
      {
        "id": "8157367a532e00107109ddeeff7b122c"
      }
    ],
    "update": [],
    "found": []
    }
  },
  "responseCode": 201
  }
}

サンプル cURL 要求

# Example passing the build details
curl -X POST "https://instance.servicenow.com/api/sn_devops/devops/package/registration?toolId=f0ca45679323008b52f3b457415ae6"
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{\
"name": "sentimentpackage",\
"artifacts": [\
{\
"name": "sa-web.jar",\
"repositoryName": "services-1031",\
"pipelineName": "spring-boot-app",\
"taskExecutionNumber": "160",\
"stageName": "Build",\
"branchName": "primary"\
},\
{\
"name": "sa-frontend.jar",\
"repositoryName": "services-1031",\
"pipelineName": "spring-boot-fe",\
"taskExecutionNumber": "991",\
"stageName": "Build",\
"branchName": "primary"\
}\
],\
"pipelineName": "spring-boot-app",\
"taskExecutionNumber": "160",\
"stageName": "Build",\
"branchName": "primary"\
}"

応答：要求がステージング済みパッケージを作成しました：

{
"result": {
  "status": "Success",
  "response": {
    "artifact_register_requests": {
      "create": [
        { 
          "id": "4628f276532e00107109ddeeff7b1245"
        },
        {
          "id": "4e28f276532e00107109ddeeff7b1245"
        },
        {
          "id": "ce28f276532e00107109ddeeff7b1245"
        }
      ],
      "update": [],
      "found": []
    }
  }, 
  "responseCode": 201 
 }
}

DevOps - POST /devops/tool/{capability}

カスタム DevOps サブフローで処理するために、渡されたペイロードを受信イベント [sn_devops_inbound] テーブルにポストします。

渡された capability パラメーターで指定された、ツールの関連 Webhook からこのエンドポイントを呼び出します。渡されたペイロードを処理するカスタムサブフローは、ServiceNow インスタンスで既に定義されている必要があります。事前定義されたスケジュールに基づいて、DevOps マスターフローは受信イベントテーブルから Webhook イベント情報を取得し、それをカスタムサブフローに渡し、それによりペイロードが処理されます。カスタムサブフローの作成の詳細については、「 DevOps サブフローの作成」を参照してください。

テストツール統合の詳細については、「 DevOps テストツール統合」を参照してください。

カスタム DevOps ツールのこのエンドポイントを呼び出す前に、sn_devops.DevOpsOrchestrationToolIntegrationHandler から handleTool() および getNativeIdForOrchestrationTask() メソッドを実装する必要があります。詳細については、「DevOpsOrchestrationToolIntegrationHandler - スコープ付き DevOpsOrchestrationToolIntegrationHandler - スコープ付き」を参照してください。

注:

バージョン 1.34.1 以降、この API の新しいバージョンが導入されています。この API を使用すると、適応認証ポリシーが期待どおりに実行されない場合があります。これらのポリシーの詳細については、「 Adaptive authentication」を参照してください。

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/tool/{capability}

デフォルトの URL：/api/sn_devops/devops/tool/{capability}

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 79. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列
capability	受信イベントテーブルに格納するペイロードを渡すツールのタイプ。有効な値 (値の大文字と小文字を区別しない)： artifact code orchestration plan test データタイプ：文字列

表 : 80. クエリパラメーター
名前	説明
orchestrationToolId	オプション。関連するパイプラインが属するオーケストレーションツールのSys_id。capability要求パラメーターが`テスト`または`ソフトウェア品質`に設定されている場合は、orchestrationToolIdが必要です。 toolId パラメーターの値が、orchestrationToolId パラメーターが渡されない場合のデフォルトのオーケストレーションツールです。データタイプ：文字列
testType	capability が `test` に設定されている場合は必須です。実行中のテストのタイプ。データタイプ：文字列テーブル:このパラメーターの有効な値は、テストタイプ [sn_devops_test_type] テーブルの [テストタイプ] 列の値です。
toolId	必須です。エンドポイントが呼び出されているツールの sys_id。データタイプ：文字列

表 : 81. 要求本文パラメーター
名前	説明
ツール依存	ツールによってペイロードのコンテンツが決定されます。

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 82. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。
認証	v2 以降、この API はトークンベースの認証をサポートしています。トークンは、ツール [sn_devops_tool] テーブルにあるツールレコードの [ トークンのコピー ] ボタンをクリックして取得できます。トークンは、Authorization: の形式で認証ヘッダーで使用できます `sn_devops。DevOpsToken <tool_sys_id>:<tool_token>`。注: 基本認証の詳細 (ユーザー名とパスワード) がトークン付きの認証ヘッダーに加えて指定されている場合、基本認証が優先されます。 devops.systemユーザーがインスタンスで利用できない場合は、[トークンベースの認証が成功した後にこのユーザーに切り替え] プロパティを使用します。このプロパティを使用すると、トークン認証を完了するために必要な sn_devops.integration ロールを持つユーザーを設定できます。詳細については、「DevOps Change Velocity properties」を参照してください。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 83. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 84. ステータスコード
ステータスコード	説明
201	要求が正常に完了しました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
401	認証が無効か見つかりません。
500	内部サーバーエラー。サーバー側のコードで論理エラーが発生しました。

応答本文のパラメーター


名前	説明
details	すべてのエラー条件のエントリ。データタイプ：オブジェクト `"details": { "errors": [Array] }`
details.errors	単一のエラーの説明。データタイプ：オブジェクトのアレイ `"errors": [ { "message": "String" } ]`
details.errors.message	詳細なエラーメッセージ。 `要求にパスパラメーターがありません`：呼び出しにパスパラメーターが含まれていません。 `要求に capability パスパラメーターがありません`：呼び出しに capability パスパラメーターが含まれていませんでした。 `サポートされていない機能タイプ`：指定された capability パラメーターが有効な値ではありません。データタイプ：文字列
status	「成功」や「データエラー」などの応答ステータス。データタイプ：文字列
sys_id	受信イベントテーブルに作成されたレコードの sys_id。データタイプ：文字列

アーティファクトのサンプル cURL 要求

curl -X POST "https://instance.service-now.com/api/sn_devops/v1/tool/artifact?toolId=3b59043ee4ea556e6850d61bc1a77e8a" 
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{
   "artifacts": [
      {
         "name": "sp-boot-app",
         "version": "1.320",
         "semanticVersion": "1.320.0",
         "repositoryName": "sp-boot-app-repo"
      }
   ],
   "pipelineName": "spring-boot-app-gitea",
   "taskExecutionNumber": "320",
   "stageName": "Build"
}"

成功応答：

{
   "result": {
      "status": "Success",
      "sysId": "33c57245dbf68410bc8cdd384b961966"
   }
}

アーティファクトのサンプル cURL 要求

curl -X POST "https://instance.service-now.com/api/sn_devops/v1/tool/artifact?toolId=3b59043ee4ea556e6850d61bc1a77e8a" 
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\ 
-d "{\
   "timestamp": "2020-01-11T00:52:01.541+0000",\
   "nodeId": "137BEECF-E1BF7BC1-90212D1C-0749A6D4-BC670F6B",\
   "initiator": "admin/172.17.0.1",\
   "repositoryName": "maven-releases29",\
   "action": "CREATED",\
   "component": {\
      "id": "2a59043ed2ea556e6850d61bc1a77c7b",\
      "componentId": "c3AtYm9vdC1hcHAtcmVwbzoyYTU5MDQzZWQyZWE1NTZlNjg1MGQ2MWJjMWE3N2M3Yg",\
      "format": "maven2",\
      "name": "sentiment-analysis-web",\
      "group": "com.spboot",\
      "version": "1.1"\
   }\
}"

エラー応答：

{
   "result": {
      "status": "Data Error",
      "details": {
         "errors": [
            {
               "message": "Unsupported capability type"
            }
         ]
      }
   }
}

コードのサンプル cURL 要求

curl "https://instance.service-now.com/api/sn_devops/devops/tool/code?toolId=8d4f56598702c510f894419d0ebb35aa&testType=junit" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   "commits": [
      {
         "totalFiles": 1,
         "nativeIdList": [
            "49",
            "50"
         ],
         "id": "f14732d0cc854ce3ec374b97ecd4ec3c383386cd",
         "url": "https://dev.azure.com/xyzabcd/adoTests/_git/DeployableRepo/commit/f14732d0cc854ce3ec374b97ecd4ec3c383386cd",
         "apiURL": "https://dev.azure.com/xyzabcd/9fe32a65-60a5-46fe-bc8d-11a92bf059f9/_apis/git/repositories/8d7ba019-1739-431c-beb4-6025dd41f1ac/commits/f14732d0cc854ce3ec374b97ecd4ec3c383386cd",
         "message": "Fixes #49 and #50",
         "committedDate": "2022-03-23T11:59:46Z",
         "committer": {
            "email": "xyz.abcd@email.com"
         },
         "details": [
            {
               "action": "edit",
               "changes": "",
               "file": "/LICENSE",
               "additions": 0,
               "deletions": 0,
               "totalChanges": 0
            }
         ]
      }
   ],
   "repository": {
      "id": "8d7ba019-1739-431c-beb4-6025dd41f1ac",
      "name": "DeployableRepo",
      "url": "https://dev.azure.com/xyzabcd/adoTests/_git/DeployableRepo"
   },
   "branch": {
      "name": "refs/heads/master",
      "url": "https://dev.azure.com/xyzabcd/adoTests/_git/DeployableRepo?version=GBmaster"
   }
}" \
--user 'username':'passsword'

成功応答：

{
   "result": {
      "status": "Success",
      "sysId: "1f8e586b879e85100f71cbfc0ebb3526"
   }
}

オーケストレーションのサンプル cURL 要求

curl "https://instance.service-now.com/api/sn_devops/devops/tool/orchestration?toolId=8d4f56598702c510f894419d0ebb35aa&testType=junit" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  "toolId": "d450f5c887e609100f71cbfc0ebb35e5",
  "buildNumber": 5676,
  "nativeId": "adoTests/DeployableRepo#deploy#5676",
  "pipelineId": "2",
  "name": "adoTests/DeployableRepo#deploy",
  "id": "adoTests/DeployableRepo#deploy#5676",
  "url": "https://dev.azure.com/xyzabcd/_build/results?buildId=5676#deploy/",
  "previousAttemptUrl": "",
  "attemptNumber": 1,
  "pipelineExecutionUrl": "https://dev.azure.com/xyzabcd/_build/results?buildId=5676",
  "orchestrationTaskUrl": "https://dev.azure.com/xyzabcd/adoTests/_build?name=DeployableRepo#deploy",
  "orchestrationTaskName": "adoTests/DeployableRepo #deploy",
  "orchestrationTask": {
    "orchestrationTaskName": "adoTests/DeployableRepo#deploy",
    "toolId": "d450f5c887e609100f71cbfc0ebb35e5",
    "orchestrationTaskURL": "https://dev.azure.com/xyzabcd/adoTests/_build?name=DeployableRepo#deploy",
    "stageName": "deploy"
  },
  "upstreamTaskUrl": [],
  "result": "building",
  "startDateTime": "2022-03-23 12:01:31",
  "log": "https://dev.azure.com/xyzabcd/adoTests/_build/results?buildId=5676&view=logs&j=5264e576-3c6f-51f6-f055-fab409685f20",
  "logUrl": "https://dev.azure.com/xyzabcd/adoTests/_build/results?buildId=5676&view=logs&j=5264e576-3c6f-51f6-f055-fab409685f20"
}" \
--user 'username':'password'

成功応答：

{
   "result": {
      "status": "Success",
      "sysId: "37dfd8a7879e85100f71cbfc0ebb35c0"
   }
}

計画のサンプル cURL 要求

curl "https://instance.service-now.com/api/sn_devops/devops/tool/plan?toolId=8d4f56598702c510f894419d0ebb35aa&testType=junit" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   "id": "1053",
   "type": "bug",
   "state": "planned",
   "shortDescription": "Title - Work Item test in 1.33.3",
   "createdDateTime": "2022-03-23T10:45:53.02Z",
   "parentId": "",
   "url": "https://dev.azure.com/xyzabcd/9fe32a65-60a5-46fe-bc8d-11a92bf059f9/_workitems/edit/1053",
   "version": {
      "id": "adoTests",
      "shortDescription": "adoTests",
      "createdDateTime": "2022-03-23T10:46:12.355Z",
      "url": "https://dev.azure.com/xyzabcd/adoTests",
      "app": {
         "id": "adoTests",
         "shortDescription": "adoTests",
         "createdDateTime": "2022-03-23T10:46:12.355Z",
         "url": "https://dev.azure.com/xyzabcd/9fe32a65-60a5-46fe-bc8d-11a92bf059f9/_workitems/edit/1053"
      }
   },
   "app": {
      "id": "adoTests",
      "shortDescription": "adoTests",
      "createdDateTime": "2022-03-23T10:46:12.355Z",
      "url": "https://dev.azure.com/xyzabcd/adoTests"
   },
   "native_type": "Issue",
   "native_state": "To Do",
   "assignedTo": {
      "name": "Xyz Abcd",
      "userName": "xyz.abcd@email.com",
      "id": "84c92fcd-e08b-6a5f-a8a6-ccda27055560",
      "email": "xyz.abcd@email.com"
   },
   "createdBy": {
      "name": "Xyz Abcd",
      "userName": "xyz.abcd@email.com",
      "id": "84c92fcd-e08b-6a5f-a8a6-ccda27055560",
      "email": "xyz.abcd@email.com"
   }
}" \
--user 'username':'password'

成功応答：

{
   "result": {
      "status": "Success",
      "sysId: "533020eb879e85100f71cbfc0ebb3591"
   }
}

テストのサンプル cURL 要求

curl "https://instance.service-now.com/api/sn_devops/devops/tool/test?toolId=8d4f56598702c510f894419d0ebb35aa&testType=junit" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   "attemptNumber": 1,
   "blockedTests": 0,
   "buildNumber": 675,
   "duration": 0.079,
   "failedTests": 0,
   "finishTime": "2022-03-23T12:02:25.957Z",
   "name": "adoTests/DeployableRepo/Test #675-2982",
   "passedTests": 20,
   "pipelineName": "adoTests/DeployableRepo",
   "skippedTests": 0,
   "stageName": "Test",
   "startTime": "2022-03-23T12:02:24.36Z",
   "taskExecutionUrl": "https://dev.azure.com/xyzabcd/adoTests/_build/results?buildId=675#Test/{Job name}",
   "totalTests": 20,
   "url": "https://dev.azure.com/xyzabcd/adoTests/_TestManagement/Runs?runId=2982&_a=runCharts"
}" \
--user 'username':'password'

成功応答：

{
   "result": {
      "status": "Success",
      "sysId: "fd3fdc6b879e85100f71cbfc0ebb356a"
   }
}

DevOps - POST /devops/tool/event/{sn_tool_id}

構築済みサブフローで処理するために、GitHub、Jira、または Bitbucket から渡されたペイロードをイベント [sn_devops_event] テーブルにポストします。

このエンドポイントを呼び出す前に、使用しているツールとの統合を作成する必要があります。

GitHub、Jira、Bitbucket 以外のツールからのイベントを処理するには、代わりに DevOps - POST /devops/tool/{capability} エンドポイントを使用します。

注:

バージョン 1.34.1 以降、この API の新しいバージョンが導入されています。この API を使用すると、適応認証ポリシーが期待どおりに実行されない場合があります。これらのポリシーの詳細については、「 Adaptive authentication」を参照してください。

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/tool/event/{sn_tool_id}

デフォルトの URL：/api/sn_devops/devops/tool/event/{sn_tool_id}

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 85. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列
sn_tool_id	要求に使用するツールの sys_id。データタイプ：文字列テーブル:DevOps ツール [sn_devops_tool]

表 : 86. クエリパラメーター
名前	説明
なし

表 : 87. 要求本文パラメーター
名前	説明
ツール依存	ツールによってペイロードのコンテンツが決定されます。ペイロードは、ツールの Webhook 情報の下にあります。

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 88. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。
認証	v2 以降、この API はトークンベースの認証をサポートしています。トークンは、ツール [sn_devops_tool] テーブルにあるツールレコードの [ トークンのコピー ] ボタンをクリックして取得できます。トークンは、Authorization: の形式で認証ヘッダーで使用できます `sn_devops。DevOpsToken <tool_sys_id>:<tool_token>`。注: 基本認証の詳細 (ユーザー名とパスワード) がトークン付きの認証ヘッダーに加えて指定されている場合、基本認証が優先されます。 devops.systemユーザーがインスタンスで利用できない場合は、[トークンベースの認証が成功した後にこのユーザーに切り替え] プロパティを使用します。このプロパティを使用すると、トークン認証を完了するために必要な sn_devops.integration ロールを持つユーザーを設定できます。詳細については、「DevOps Change Velocity properties」を参照してください。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 89. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 90. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
201	要求が正常に完了しました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
401	認証が無効か見つかりません。
500	内部サーバーエラー。サーバー側のコードで論理エラーが発生しました。

応答本文のパラメーター


名前	説明
result	応答ステータス。可能な値： `失敗`:ツール ID が正しくありません。イベントは作成されません。 `success`：イベント [sn_devops_event] テーブルにイベントが作成されました。ただし、誤ったペイロードが指定された場合、イベントステータスが [エラー] になる場合があります。データタイプ：文字列

cURL 要求

GitHub

curl "https://instance.service-now.com/api/sn_devops/devops/tool/event/46a07b2f471e011028c23a34846d43b2" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   "ref": "refs/heads/master",
   "before": "59078a17cad1f4129754971c808d6c399b6141a5",
   "after": "b7957bab20835449c4d597fee24075a9a5a2c099",
   "repository": {
      "id": 252146476,
      "node_id": "MDEwOlJlcG9zaXRvcnkyNTIxNDY0NzY=",
      "name": "test",
      "full_name": "Xyz002/test",
      "private": false,
      "owner": {
         "name": "Xyz002",
         "email": "62993516+Xyz002@users.noreply.github.com",
         "login": "Xyz002",
         "id": 62993516,
         "node_id": "MDQ6VXNlcjYyOTkzNTE2",
         "avatar_url": "https://avatars.githubusercontent.com/u/62993516?v=4",
         "gravatar_id": "",
         "url": "https://api.github.com/users/Xyz002",
         "html_url": "https://github.com/Xyz002",
         "followers_url": "https://api.github.com/users/Xyz002/followers",
         "following_url": "https://api.github.com/users/Xyz002/following{/other_user}",
         "gists_url": "https://api.github.com/users/Xyz002/gists{/gist_id}",
         "starred_url": "https://api.github.com/users/Xyz002/starred{/owner}{/repo}",
         "subscriptions_url": "https://api.github.com/users/Xyz002/subscriptions",
         "organizations_url": "https://api.github.com/users/Xyz002/orgs",
         "repos_url": "https://api.github.com/users/Xyz002/repos",
         "events_url": "https://api.github.com/users/Xyz002/events{/privacy}",
         "received_events_url": "https://api.github.com/users/Xyz002/received_events",
         "type": "User",
         "site_admin": false
      },
      "html_url": "https://github.com/Xyz002/test",
      "description": null,
      "fork": false,
      "url": "https://github.com/Xyz002/test",
      "forks_url": "https://api.github.com/repos/Xyz002/test/forks",
      "keys_url": "https://api.github.com/repos/Xyz002/test/keys{/key_id}",
      "collaborators_url": "https://api.github.com/repos/Xyz002/test/collaborators{/collaborator}",
      "teams_url": "https://api.github.com/repos/Xyz002/test/teams",
      "hooks_url": "https://api.github.com/repos/Xyz002/test/hooks",
      "issue_events_url": "https://api.github.com/repos/Xyz002/test/issues/events{/number}",
      "events_url": "https://api.github.com/repos/Xyz002/test/events",
      "assignees_url": "https://api.github.com/repos/Xyz002/test/assignees{/user}",
      "branches_url": "https://api.github.com/repos/Xyz002/test/branches{/branch}",
      "tags_url": "https://api.github.com/repos/Xyz002/test/tags",
      "blobs_url": "https://api.github.com/repos/Xyz002/test/git/blobs{/sha}",
      "git_tags_url": "https://api.github.com/repos/Xyz002/test/git/tags{/sha}",
      "git_refs_url": "https://api.github.com/repos/Xyz002/test/git/refs{/sha}",
      "trees_url": "https://api.github.com/repos/Xyz002/test/git/trees{/sha}",
      "statuses_url": "https://api.github.com/repos/Xyz002/test/statuses/{sha}",
      "languages_url": "https://api.github.com/repos/Xyz002/test/languages",
      "stargazers_url": "https://api.github.com/repos/Xyz002/test/stargazers",
      "contributors_url": "https://api.github.com/repos/Xyz002/test/contributors",
      "subscribers_url": "https://api.github.com/repos/Xyz002/test/subscribers",
      "subscription_url": "https://api.github.com/repos/Xyz002/test/subscription",
      "commits_url": "https://api.github.com/repos/Xyz002/test/commits{/sha}",
      "git_commits_url": "https://api.github.com/repos/Xyz002/test/git/commits{/sha}",
      "comments_url": "https://api.github.com/repos/Xyz002/test/comments{/number}",
      "issue_comment_url": "https://api.github.com/repos/Xyz002/test/issues/comments{/number}",
      "contents_url": "https://api.github.com/repos/Xyz002/test/contents/{+path}",
      "compare_url": "https://api.github.com/repos/Xyz002/test/compare/{base}...{head}",
      "merges_url": "https://api.github.com/repos/Xyz002/test/merges",
      "archive_url": "https://api.github.com/repos/Xyz002/test/{archive_format}{/ref}",
      "downloads_url": "https://api.github.com/repos/Xyz002/test/downloads",
      "issues_url": "https://api.github.com/repos/Xyz002/test/issues{/number}",
      "pulls_url": "https://api.github.com/repos/Xyz002/test/pulls{/number}",
      "milestones_url": "https://api.github.com/repos/Xyz002/test/milestones{/number}",
      "notifications_url": "https://api.github.com/repos/Xyz002/test/notifications{?since,all,participating}",
      "labels_url": "https://api.github.com/repos/Xyz002/test/labels{/name}",
      "releases_url": "https://api.github.com/repos/Xyz002/test/releases{/id}",
      "deployments_url": "https://api.github.com/repos/Xyz002/test/deployments",
      "created_at": 1585737871,
      "updated_at": "2022-01-04T14:37:36Z",
      "pushed_at": 1648103939,
      "git_url": "git://github.com/Xyz002/test.git",
      "ssh_url": "git@github.com:Xyz002/test.git",
      "clone_url": "https://github.com/Xyz002/test.git",
      "svn_url": "https://github.com/Xyz002/test",
      "homepage": null,
      "size": 1378,
      "stargazers_count": 0,
      "watchers_count": 0,
      "language": "Java",
      "has_issues": true,
      "has_projects": true,
      "has_downloads": true,
      "has_wiki": true,
      "has_pages": false,
      "forks_count": 0,
      "mirror_url": null,
      "archived": false,
      "disabled": false,
      "open_issues_count": 2,
      "license": null,
      "allow_forking": true,
      "is_template": false,
      "topics": [],
      "visibility": "public",
      "forks": 0,
      "open_issues": 2,
      "watchers": 0,
      "default_branch": "master",
      "stargazers": 0,
      "master_branch": "master"
   },
   "pusher": {
      "name": "Xyz002",
      "email": "62993516+Xyz002@users.noreply.github.com"
   },
   "sender": {
      "login": "Xyz002",
      "id": 62993516,
      "node_id": "MDQ6VXNlcjYyOTkzNTE2",
      "avatar_url": "https://avatars.githubusercontent.com/u/62993516?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/Xyz002",
      "html_url": "https://github.com/Xyz002",
      "followers_url": "https://api.github.com/users/Xyz002/followers",
      "following_url": "https://api.github.com/users/Xyz002/following{/other_user}",
      "gists_url": "https://api.github.com/users/Xyz002/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/Xyz002/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/Xyz002/subscriptions",
      "organizations_url": "https://api.github.com/users/Xyz002/orgs",
      "repos_url": "https://api.github.com/users/Xyz002/repos",
      "events_url": "https://api.github.com/users/Xyz002/events{/privacy}",
      "received_events_url": "https://api.github.com/users/Xyz002/received_events",
      "type": "User",
      "site_admin": false
   },
   "created": false,
   "deleted": false,
   "forced": false,
   "base_ref": null,
   "compare": "https://github.com/Xyz002/test/compare/59078a17cad1...b7957bab2083",
   "commits": [
      {
         "id": "b7957bab20835449c4d597fee24075a9a5a2c099",
         "tree_id": "fa8d699762ec0a25868fa1ab4d299da392f0a974",
         "distinct": true,
         "message": "updated this file",
         "timestamp": "2022-03-24T12:08:59+05:30",
         "url": "https://github.com/Xyz002/test/commit/b7957bab20835449c4d597fee24075a9a5a2c099",
         "author": {
            "name": "Xyz002",
            "email": "62993516+Xyz002@users.noreply.github.com",
            "username": "Xyz002"
         },
         "committer": {
            "name": "GitHub",
            "email": "noreply@github.com",
            "username": "web-flow"
         },
         "added": [],
         "removed": [],
         "modified": [
            "README.me"
         ]
      }
   ],
   "head_commit": {
      "id": "b7957bab20835449c4d597fee24075a9a5a2c099",
      "tree_id": "fa8d699762ec0a25868fa1ab4d299da392f0a974",
      "distinct": true,
      "message": "updated this file",
      "timestamp": "2022-03-24T12:08:59+05:30",
      "url": "https://github.com/Xyz002/test/commit/b7957bab20835449c4d597fee24075a9a5a2c099",
      "author": {
         "name": "Xyz002",
         "email": "62993516+Xyz002@users.noreply.github.com",
         "username": "Xyz002"
      },
      "committer": {
         "name": "GitHub",
         "email": "noreply@github.com",
         "username": "web-flow"
      },
      "added": [],
      "removed": [],
      "modified": [
         "README.me"
      ]
   },
   "sn_tool_id": "46a07b2f471e011028c23a34846d43b2"
}" \
--user 'username':'password'

成功応答：

{
   "result": "success"
}

cURL 要求

Jira

curl "https://instance.service-now.com/api/sn_devops/devops/tool/event/9ed237af471e011028c23a34846d4327" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   "timestamp": 1648104684180,
   "webhookEvent": "jira:issue_created",
   "issue_event_type_name": "issue_created",
   "user": {
      "self": "http://jira1.sndevops.xyz/rest/api/2/user?username=admin",
      "name": "admin",
      "key": "admin",
      "emailAddress": "username@email.com",
      "avatarUrls": {
         "48x48": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=48",
         "24x24": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=24",
         "16x16": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=16",
         "32x32": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=32"
      },
      "displayName": "Administrator",
      "active": true,
      "timeZone": "America/Los_Angeles"
   },
   "issue": {
      "id": "84800",
      "self": "http://jira1.sndevops.xyz/rest/api/2/issue/84800",
      "key": "BAL-2",
      "fields": {
         "issuetype": {
            "self": "http://jira1.sndevops.xyz/rest/api/2/issuetype/10002",
            "id": "10002",
            "description": "A task that needs to be done.",
            "iconUrl": "http://jira1.sndevops.xyz/secure/viewavatar?size=xsmall&avatarId=10318&avatarType=issuetype",
            "name": "Task",
            "subtask": false,
            "avatarId": 10318
         },
         "timespent": null,
         "project": {
            "self": "http://jira1.sndevops.xyz/rest/api/2/project/10507",
            "id": "10507",
            "key": "BAL",
            "name": "balu_devops",
            "projectTypeKey": "software",
            "avatarUrls": {
               "48x48": "http://jira1.sndevops.xyz/secure/projectavatar?avatarId=10324",
               "24x24": "http://jira1.sndevops.xyz/secure/projectavatar?size=small&avatarId=10324",
               "16x16": "http://jira1.sndevops.xyz/secure/projectavatar?size=xsmall&avatarId=10324",
               "32x32": "http://jira1.sndevops.xyz/secure/projectavatar?size=medium&avatarId=10324"
            }
         },
         "fixVersions": [],
         "aggregatetimespent": null,
         "resolution": null,
         "customfield_10302": null,
         "customfield_10105": null,
         "resolutiondate": null,
         "workratio": 0,
         "lastViewed": null,
         "watches": {
            "self": "http://jira1.sndevops.xyz/rest/api/2/issue/BAL-2/watchers",
            "watchCount": 0,
            "isWatching": false
         },
         "created": "2022-03-24T06:51:22.896+0000",
         "priority": {
            "self": "http://jira1.sndevops.xyz/rest/api/2/priority/3",
            "iconUrl": "http://jira1.sndevops.xyz/images/icons/priorities/medium.svg",
            "name": "Medium",
            "id": "3"
         },
         "customfield_10100": "0|i0cprw:",
         "customfield_10101": "SCRUMBOARD-14",
         "customfield_10300": null,
         "labels": [],
         "timeestimate": 240,
         "aggregatetimeoriginalestimate": 300,
         "versions": [],
         "issuelinks": [
            {
               "id": "10701",
               "self": "http://jira1.sndevops.xyz/rest/api/2/issueLink/10701",
               "type": {
                  "id": "10000",
                  "name": "Blocks",
                  "inward": "is blocked by",
                  "outward": "blocks",
                  "self": "http://jira1.sndevops.xyz/rest/api/2/issueLinkType/10000"
               },
               "outwardIssue": {
                  "id": "84741",
                  "key": "BAL-1",
                  "self": "http://jira1.sndevops.xyz/rest/api/2/issue/84741",
                  "fields": {
                     "summary": "log4jtesting",
                     "status": {
                        "self": "http://jira1.sndevops.xyz/rest/api/2/status/3",
                        "description": "This issue is being actively worked on at the moment by the assignee.",
                        "iconUrl": "http://jira1.sndevops.xyz/images/icons/statuses/inprogress.png",
                        "name": "In Progress",
                        "id": "3",
                        "statusCategory": {
                           "self": "http://jira1.sndevops.xyz/rest/api/2/statuscategory/4",
                           "id": 4,
                           "key": "indeterminate",
                           "colorName": "yellow",
                           "name": "In Progress"
                        }
                     },
                     "priority": {
                        "self": "http://jira1.sndevops.xyz/rest/api/2/priority/3",
                        "iconUrl": "http://jira1.sndevops.xyz/images/icons/priorities/medium.svg",
                        "name": "Medium",
                        "id": "3"
                     },
                     "issuetype": {
                        "self": "http://jira1.sndevops.xyz/rest/api/2/issuetype/10004",
                        "id": "10004",
                        "description": "A problem which impairs or prevents the functions of the product.",
                        "iconUrl": "http://jira1.sndevops.xyz/secure/viewavatar?size=xsmall&avatarId=10303&avatarType=issuetype",
                        "name": "Bug",
                        "subtask": false,
                        "avatarId": 10303
                     }
                  }
               }
            }
         ],
         "assignee": {
            "self": "http://jira1.sndevops.xyz/rest/api/2/user?username=admin",
            "name": "admin",
            "key": "admin",
            "emailAddress": "username@email.com",
            "avatarUrls": {
               "48x48": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=48",
               "24x24": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=24",
               "16x16": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=16",
               "32x32": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=32"
            },
            "displayName": "Administrator",
            "active": true,
            "timeZone": "America/Los_Angeles"
         },
         "updated": "2022-03-24T06:51:22.896+0000",
         "status": {
            "self": "http://jira1.sndevops.xyz/rest/api/2/status/10000",
            "description": "",
            "iconUrl": "http://jira1.sndevops.xyz/",
            "name": "To Do",
            "id": "10000",
            "statusCategory": {
               "self": "http://jira1.sndevops.xyz/rest/api/2/statuscategory/2",
               "id": 2,
               "key": "new",
               "colorName": "blue-gray",
               "name": "To Do"
            }
         },
         "components": [],
         "timeoriginalestimate": 300,
         "description": "Task description",
         "timetracking": {
            "originalEstimate": "5m",
            "remainingEstimate": "4m",
            "originalEstimateSeconds": 300,
            "remainingEstimateSeconds": 240
         },
         "customfield_10203": null,
         "customfield_10204": null,
         "customfield_10205": null,
         "attachment": [],
         "aggregatetimeestimate": 240,
         "summary": "Task Summary",
         "creator": {
            "self": "http://jira1.sndevops.xyz/rest/api/2/user?username=admin",
            "name": "admin",
            "key": "admin",
            "emailAddress": "username@email.com",
            "avatarUrls": {
               "48x48": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=48",
               "24x24": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=24",
               "16x16": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=16",
               "32x32": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=32"
            },
            "displayName": "Administrator",
            "active": true,
            "timeZone": "America/Los_Angeles"
         },
         "subtasks": [],
         "reporter": {
            "self": "http://jira1.sndevops.xyz/rest/api/2/user?username=admin",
            "name": "admin",
            "key": "admin",
            "emailAddress": "username@email.com",
            "avatarUrls": {
               "48x48": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=48",
               "24x24": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=24",
               "16x16": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=16",
               "32x32": "https://www.gravatar.com/avatar/eccd6ec2c978f1f1d4a1fed4e81265eb?d=mm&s=32"
            },
            "displayName": "Administrator",
            "active": true,
            "timeZone": "America/Los_Angeles"
         },
         "customfield_10000": "{summaryBean=com.atlassian.jira.plugin.devstatus.rest.SummaryBean@2ccf8c6[summary={pullrequest=com.atlassian.jira.plugin.devstatus.rest.SummaryItemBean@fbc42d4[overall=PullRequestOverallBean{stateCount=0, state='OPEN', details=PullRequestOverallDetails{openCount=0, mergedCount=0, declinedCount=0}},byInstanceType={}], build=com.atlassian.jira.plugin.devstatus.rest.SummaryItemBean@71e33347[overall=com.atlassian.jira.plugin.devstatus.summary.beans.BuildOverallBean@1c24654d[failedBuildCount=0,successfulBuildCount=0,unknownBuildCount=0,count=0,lastUpdated=<null>,lastUpdatedTimestamp=<null>],byInstanceType={}], review=com.atlassian.jira.plugin.devstatus.rest.SummaryItemBean@1ea8fb17[overall=com.atlassian.jira.plugin.devstatus.summary.beans.ReviewsOverallBean@6dc95939[stateCount=0,state=<null>,dueDate=<null>,overDue=false,count=0,lastUpdated=<null>,lastUpdatedTimestamp=<null>],byInstanceType={}], deployment-environment=com.atlassian.jira.plugin.devstatus.rest.SummaryItemBean@55826cc[overall=com.atlassian.jira.plugin.devstatus.summary.beans.DeploymentOverallBean@3ae93527[topEnvironments=[],showProjects=false,successfulCount=0,count=0,lastUpdated=<null>,lastUpdatedTimestamp=<null>],byInstanceType={}], repository=com.atlassian.jira.plugin.devstatus.rest.SummaryItemBean@6340012e[overall=com.atlassian.jira.plugin.devstatus.summary.beans.CommitOverallBean@44678cee[count=0,lastUpdated=<null>,lastUpdatedTimestamp=<null>],byInstanceType={}], branch=com.atlassian.jira.plugin.devstatus.rest.SummaryItemBean@4dbce8[overall=com.atlassian.jira.plugin.devstatus.summary.beans.BranchOverallBean@737ee1cb[count=0,lastUpdated=<null>,lastUpdatedTimestamp=<null>],byInstanceType={}]},errors=[],configErrors=[]], devSummaryJson={\"cachedValue\":{\"errors\":[],\"configErrors\":[],\"summary\":{\"pullrequest\":{\"overall\":{\"count\":0,\"lastUpdated\":null,\"stateCount\":0,\"state\":\"OPEN\",\"details\":{\"openCount\":0,\"mergedCount\":0,\"declinedCount\":0,\"total\":0},\"open\":true},\"byInstanceType\":{}},\"build\":{\"overall\":{\"count\":0,\"lastUpdated\":null,\"failedBuildCount\":0,\"successfulBuildCount\":0,\"unknownBuildCount\":0},\"byInstanceType\":{}},\"review\":{\"overall\":{\"count\":0,\"lastUpdated\":null,\"stateCount\":0,\"state\":null,\"dueDate\":null,\"overDue\":false,\"completed\":false},\"byInstanceType\":{}},\"deployment-environment\":{\"overall\":{\"count\":0,\"lastUpdated\":null,\"topEnvironments\":[],\"showProjects\":false,\"successfulCount\":0},\"byInstanceType\":{}},\"repository\":{\"overall\":{\"count\":0,\"lastUpdated\":null},\"byInstanceType\":{}},\"branch\":{\"overall\":{\"count\":0,\"lastUpdated\":null},\"byInstanceType\":{}}}},\"isStale\":false}}",
         "aggregateprogress": {
            "progress": 0,
            "total": 240,
            "percent": 0
         },
         "customfield_10200": null,
         "customfield_10201": null,
         "customfield_10202": null,
         "environment": null,
         "duedate": "2022-03-24",
         "progress": {
            "progress": 0,
            "total": 240,
            "percent": 0
         },
         "comment": {
            "comments": [],
            "maxResults": 0,
            "total": 0,
            "startAt": 0
         },
         "votes": {
            "self": "http://jira1.sndevops.xyz/rest/api/2/issue/BAL-2/votes",
            "votes": 0,
            "hasVoted": false
         },
         "worklog": {
            "startAt": 0,
            "maxResults": 20,
            "total": 0,
            "worklogs": []
         }
      }
   },
   "changelog": {
      "id": "14401",
      "items": [
         {
            "field": "Link",
            "fieldtype": "jira",
            "from": null,
            "fromString": null,
            "to": "BAL-1",
            "toString": "This issue blocks BAL-1"
         }
      ]
   },
   "sn_tool_id": "9ed237af471e011028c23a34846d4327"
}" \
--user 'username':'password'

成功応答：

{
   "result": "success"
}

cURL 要求

Bitbucket

curl "https://instance.service-now.com/api/sn_devops/devops/tool/event/6975ecaf879e85100f71cbfc0ebb3575" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   "eventKey": "repo:refs_changed",
   "date": "2022-03-23T15:57:05+0000",
   "actor": {
      "name": "admin",
      "emailAddress": "username@email.com",
      "id": 1,
      "displayName": "Admin",
      "active": true,
      "slug": "admin",
      "type": "NORMAL",
      "links": {
         "self": [
            {
               "href": "http://bitbucket2.sndevops.xyz/users/admin"
            }
         ]
      }
   },
   "repository": {
      "slug": "testautomationrepo1",
      "id": 12,
      "name": "TestAutomationRepo1",
      "scmId": "git",
      "state": "AVAILABLE",
      "statusMessage": "Available",
      "forkable": true,
      "origin": {
         "slug": "testautomationrepo1",
         "id": 1,
         "name": "TestAutomationRepo1",
         "scmId": "git",
         "state": "AVAILABLE",
         "statusMessage": "Available",
         "forkable": true,
         "project": {
            "key": "TES",
            "id": 1,
            "name": "TestAutomation",
            "public": false,
            "type": "NORMAL",
            "links": {
               "self": [
                  {
                     "href": "http://bitbucket2.sndevops.xyz/projects/TES"
                  }
               ]
            }
         },
         "public": false,
         "links": {
            "clone": [
               {
                  "href": "ssh://git@bitbucket2.sndevops.xyz:7999/tes/testautomationrepo1.git",
                  "name": "ssh"
               },
               {
                  "href": "http://bitbucket2.sndevops.xyz/scm/tes/testautomationrepo1.git",
                  "name": "http"
               }
            ],
            "self": [
               {
                  "href": "http://bitbucket2.sndevops.xyz/projects/TES/repos/testautomationrepo1/browse"
               }
            ]
         }
      },
      "project": {
         "key": "~ADMIN",
         "id": 3,
         "name": "Admin",
         "type": "PERSONAL",
         "owner": {
            "name": "admin",
            "emailAddress": "username@email.com",
            "id": 1,
            "displayName": "Admin",
            "active": true,
            "slug": "admin",
            "type": "NORMAL",
            "links": {
               "self": [
                  {
                     "href": "http://bitbucket2.sndevops.xyz/users/admin"
                  }
               ]
            }
         },
         "links": {
            "self": [
               {
                  "href": "http://bitbucket2.sndevops.xyz/users/admin"
               }
            ]
         }
      },
      "public": false,
      "links": {
         "clone": [
            {
               "href": "http://bitbucket2.sndevops.xyz/scm/~admin/testautomationrepo1.git",
               "name": "http"
            },
            {
               "href": "ssh://git@bitbucket2.sndevops.xyz:7999/~admin/testautomationrepo1.git",
               "name": "ssh"
            }
         ],
         "self": [
            {
               "href": "http://bitbucket2.sndevops.xyz/users/admin/repos/testautomationrepo1/browse"
            }
         ]
      }
   },
   "changes": [
      {
         "ref": {
            "id": "refs/heads/master",
            "displayId": "master",
            "type": "BRANCH"
         },
         "refId": "refs/heads/master",
         "fromHash": "b482b2e232f5fbdee73feed8ca1cfb774de6976e",
         "toHash": "d783254fe6f77bc7cc079358158aeef52a457587",
         "type": "UPDATE"
      }
   ],
   "sn_tool_id": "6975ecaf879e85100f71cbfc0ebb3575"
}" \
--user 'username':'password'

成功応答：

{
   "result": "success"
}

DevOps - PUT /devops/orchestration/changeControl/{changeControlId}

指定されたオーケストレーションタスクの変更管理情報を更新します。

URL 形式

バージョニングされた URL：/api/sn_devops/{api_version}/devops/orchestration/changeControl/{changeControlId}

デフォルトの URL：/api/sn_devops/devops/orchestration/changeControl/{changeControlId}

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 91. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列
changeControlId	変更管理タスクの sys_id。コールバック [sn_devops_callback] テーブルにあります。データタイプ：文字列

表 : 92. クエリパラメーター
名前	説明
toolId	必須です。変更管理タスクに関連付けられた DevOps ツールの sys_id。データタイプ：文字列テーブル:オーケストレーションツール [sn_devops_orchestration_tool]

表 : 93. 要求本文パラメーター
名前	説明
callbackURL	必須です。関連する変更要求承認プロセスが完了したときに ServiceNow インスタンスがコールバックできる URL。このコールバックは、承認結果に基づいてパイプラインの実行を続行するか、または続行しません。データタイプ：文字列
orchestrationTaskDetails	必須です。オーケストレーションタスクの説明。データタイプ：オブジェクト `"orchestrationTaskDetails": { "message": "String", "triggerType": "String", "upstreamTaskExecutionURL": "String" }`
orchestrationTaskDetails.message	自由形式のテキストメッセージ。データタイプ：文字列
orchestrationTaskDetails.triggerType	必須です。オーケストレーションタスクが開始された方法。有効な値： scm：Git/scm ツールのコードコミットによってジョブがトリガーされました。 upstream：アップストリームのジョブがこのジョブをトリガーしました。 user：ユーザーが手動でジョブを開始しました。データタイプ：文字列
orchestrationTaskDetails.upstreamTaskExecutionURL	triggerType が `upstream` に設定されている場合は必須です。アップストリームタスク実行 URL。例：https://jenkins.mycompany.com:8080/job/Mobile-Platform-test/40/ データタイプ：文字列
orchestrationTaskURL	必須です。オーケストレーションタスクの URL。例：https://jenkins.mycompany.com:8080/orchestration_task/Mobile-Platform-deploy/ データタイプ：文字列
toolType	DevOps ツールのタイプ。有効な値：jenkins データタイプ：文字列
taskExecutionURL	必須。実行するタスクの URL。データタイプ：文字列

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 94. 要求ヘッダー
ヘッダー	説明
Accept	応答本文のデータフォーマット。application/json のみをサポートします。
認証	v2 以降、この API はトークンベースの認証をサポートしています。トークンは、ツール [sn_devops_tool] テーブルにあるツールレコードの [ トークンのコピー ] ボタンをクリックして取得できます。トークンは、Authorization: の形式で認証ヘッダーで使用できます `sn_devops。DevOpsToken <tool_sys_id>:<tool_token>`。注: 基本認証の詳細 (ユーザー名とパスワード) がトークン付きの認証ヘッダーに加えて指定されている場合、基本認証が優先されます。 devops.systemユーザーがインスタンスで利用できない場合は、[トークンベースの認証が成功した後にこのユーザーに切り替え] プロパティを使用します。このプロパティを使用すると、トークン認証を完了するために必要な sn_devops.integration ロールを持つユーザーを設定できます。詳細については、「DevOps Change Velocity properties」を参照してください。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 95. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 96. ステータスコード
ステータスコード	説明
200	要求が正常に完了しました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
401	認証が無効か見つかりません。
404	見つかりません。指定されたレコードが見つかりませんでした。
500	内部サーバーエラー。要求の処理中に予期しないエラーが発生しました。応答に、エラーに関する追加情報が含まれます。

応答本文のパラメーター


名前	説明
change_control	オーケストレーションタスクが変更管理下にあるかどうかを示すフラグ。可能な値： true：変更管理下にあります。 false：変更管理下にありません。データタイプ：ブーリアン
details	すべてのエラー条件のエントリ。データタイプ：オブジェクト `"details": { "errors": [Array] }`
details.errors	単一のエラーの説明。データタイプ：オブジェクトのアレイ `"errors": [ { "message": "String" } ]`
details.errors.message	詳細なエラーメッセージ。データタイプ：文字列

サンプル cURL 要求

curl -X PUT "https://instance.service-now.com/api/sn_devops/v1/devops/orchestration/changeControl/f0ca45679323008b52f3b457415ae6?toolId=f0ca45679323008b52f3b457415ae6"
-H "accept: application/json"\
-H "Content-Type: application/json"\
-u "username":"password"\
-d "{
  \"orchestrationTaskURL\":\"https://jenkins.mycompany.com:8080/job/Mobile-Platform-deploy/\",
  \"toolType\":\"jenkins\",
  \"callbackURL\":\"https://jenkins.mycompany.com:8080/sn-devops/964aca59-0cae-4d9b-a36d-5929f426cf31\",
\"taskExecutionURL\":\"https://jenkins.mycompany.com:8080/job/Mobile-Platform-test/40/\",  
"\orchestrationTaskName\":\"StageName\",
  \"orchestrationTaskDetails\":{
    \"message\":\"Started by upstream project \\\"Mobile-Platform-test\\\" build number 40\",
    \"triggerType\":\"upstream\",
    \"upstreamTaskExecutionURL\":\"https://jenkins.mycompany.com:8080/job/Mobile-Platform-test/40/\"}
}"

応答：

{
    "result": {
        "change_control": true
    }
}

DevOps - PUT /devops/orchestration/changeInfo/{changeInfo}

指定された変更要求のフィールドを更新します。

URL 形式

バージョニングされた URL: /api/sn_devops/{api_version}/devops/orchestration/changeInfo/{changeInfo}

デフォルト URL: /api/sn_devops/devops/orchestration/changeInfo/{changeInfo}

注:

利用可能なバージョンは、 REST API エクスプローラーで指定されます。スクリプト済み REST API の場合、[ スクリプト済み REST サービス] フォームに追加のバージョン情報があります。

サポートされている要求パラメーター

表 : 97. パスパラメーター
名前	説明
api_version	オプションアクセスするエンドポイントのバージョン。`たとえば、v1` や `v2` などです。最新以外のエンドポイントバージョンを使用する場合にのみ、この値を指定してください。データタイプ：文字列

表 : 98. クエリパラメーター
名前	説明
変更要求番号	必須。更新するオーケストレーションタスクに関連付けられた変更要求番号。データタイプ：文字列テーブル：変更要求 [change_request]

表 : 99. 要求本文パラメーター
名前	説明
データ	必須。関連する変更要求で更新するフィールドの名前と値のペア。たとえば、簡単な説明ファイルを更新するには、次のような名前と値のペアを入力します。 `"{\"short_description\": \"my short desc\" }"` state パラメーターでは、次の移行のみがサポートされています。キャンセル：ステータスをキャンセルに移行するには、変更要求ステータスを実装する必要があります。 reason パラメーターは、ステータスをキャンセルに更新するための必須入力です。クローズド：ステータスをクローズに移動するには、変更要求のステータスが [実装済み] または [実装後] である必要があります。 close_codeとclose_notesは、ステータスをクローズ済みに更新するための必須入力です。可能な値： 4:キャンセル (sn_devops.change_request.cancel_state プロパティに設定された値。) 3:クローズ済み (sn_devops.change_request.closed_state プロパティに設定された値。) データタイプ：文字列

ヘッダー

次のリクエストや応答ヘッダーは、この HTTP アクションにのみ適用されるか、またはこのアクションに別個の方法で適用されます。REST API で使用される一般的なヘッダーのリストについては、「サポートされている REST API ヘッダー」を参照してください。

表 : 100. 要求ヘッダー
ヘッダー	説明
承認	応答本文のデータフォーマット。application/json のみをサポートします。
認証	v2 以降、この API はトークンベースの認証をサポートしています。トークンは、ツール [sn_devops_tool] テーブルにあるツールレコードの [ トークンのコピー ] ボタンをクリックして取得できます。トークンは、Authorization: の形式で認証ヘッダーで使用できます `sn_devops。DevOpsToken <tool_sys_id>:<tool_token>`。注: 基本認証の詳細 (ユーザー名とパスワード) がトークン付きの認証ヘッダーに加えて指定されている場合、基本認証が優先されます。 devops.systemユーザーがインスタンスで利用できない場合は、[トークンベースの認証が成功した後にこのユーザーに切り替え] プロパティを使用します。このプロパティを使用すると、トークン認証を完了するために必要な sn_devops.integration ロールを持つユーザーを設定できます。詳細については、「DevOps Change Velocity properties」を参照してください。
Content-Type	要求本文のデータ形式。application/json のみをサポートします。

表 : 101. 応答ヘッダー
ヘッダー	説明
なし

ステータスコード

この HTTP アクションには、次のステータスコードが適用されます。REST API で使用される可能性のあるステータスコードのリストについては、「 REST API HTTP 応答コード」を参照してください。

表 : 102. ステータスコード
ステータスコード	説明
200	成功。要求が正常に処理されました。
400	要求が正しくありません。不適切な要求タイプまたは誤った要求が検出されました。
404	見つかりません。要求されたアイテムが見つかりませんでした。

応答本文のパラメーター


名前	説明
メッセージ	更新結果の説明。データタイプ：文字列
status	要求のステータス可能な値：成功:変更要求が見つかり、変更の詳細が正常に更新されました。エラー:変更要求が見つからなかったため、変更の詳細が更新されませんでした。データタイプ：文字列
updateStatus	更新のステータス。可能な値：完了エラーデータタイプ：文字列

cURL 要求

次のコード例は、CHG0030023変更要求のさまざまなフィールドを更新する方法を示しています。

curl -X PUT"
https://instance.servicenow.com/api/sn_devops/v1/devops/orchestration/changeInfo?changeRequestNumber=CHG0030023

-H "accept: application/json"\
-u "username":"password" 
- D
{
  "short_description": "Test description",
  "priority": "1",
  "start_date": "2021-02-05 08:00:00",
  "end_date": "2022-04-05 08:00:00",
  "justification": "test justification",
  "description": "test description",
  "cab_required": true,
  "comments": "This update for work notes is from jenkins file",
  "work_notes": "test work notes",
  "assignment_group": "a715cd759f2002002920bde8132e7018"
}

応答：

{
  "result": {
    "updateStatus": "Done",
    "status": "Success",
    "message": "change request update successful"
  }
}