# サービス/APIシンクレット

{% hint style="info" %}
サービス/API Thinkletは、次のコネクタ認証情報タイプをサポートしています:

* 基本
* ベアラー
* OAuth 2.0 - Client Credentials
* OAuth 2.0 - Authorization Code
* 認証なし
  {% endhint %}

サービス/APIティンクレットは、外部の公衆APIへRESTコールを実行します。 これは追加情報を取得したり、行動を要求するために使用します。

サービス/APIティンクレットは次の呼び出しメソッドをサポートしています：

* GET
* POST
* PATCH
* PUT
* DELETE

{% hint style="info" %}
サービス/APIティンクレットでサポートされるペイロードとレスポンスはJSON形式です。
{% endhint %}

<div align="left"><figure><img src="https://3549141153-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FeLm8O7QKZDn6z806e7Sv%2Fuploads%2Fgit-blob-cefd4ad6ec96ebea3a49eb625b05e42f27c84e04%2Fimage%20(649).png?alt=media" alt="" width="322"><figcaption></figcaption></figure></div>

* **名前**: サービス/APIティンクレットにユニークな名前を入力します。
* **ID**: システムは名前に基づいて自動的にIDを生成します。
* **説明（オプション）**: ティンクレットの目的とその機能を説明します。 この情報は、ワークフローを利用する他のユーザーにとって役立ちます。
* **資格情報**: 統合のための接続クレデンシャルを選択します。 最初に管理モジュールの[Connector credentials](https://docs.nexthink.com/platform/ja/configuring_nexthink/bringing-data-into-your-nexthink-instance/integrating-nexthink-with-third-party-tools/outbound-connectors/connector-credentials.md)ページで構成してください。
* **リクエストメソッド**: リクエスト接続メソッドを選択します。
* **リソース**: 接続のエンドポイントを指定します。 このページで [#setting-the-resource-path](#setting-the-resource-path) セクションを参照してください。
* **カスタムヘッダーの追加**: 追加のメタデータを渡すために最大5つのカスタムヘッダーを追加します。 代わりに **資格情報** に認証ヘッダーを追加する必要があります。
* **ペイロード**: 外部システムに送信する [JSON ペイロード](#using-database-and-workflow-values-in-payloads)を入力します。 特殊文字を含む動的な値（例えば、改行文字）は、無効な JSON にならないように適切にエスケープする必要があります。
* **JSONの解析言語を選択**して、[API呼び出しの応答からデータを収集](#collecting-data-from-api-calls)するために効果を発揮します。
  * データ選択および変換のための [出力設定を追加](#output-configuration) します。

{% hint style="warning" %}
単一のサービス/APIティンクレット内のすべての式は、選択された **JSON解析言語** を使用する必要があります。
{% endhint %}

#### リソースパスの設定

Service/API thinkletの設定から、資格情報で示された基本URLに対して呼び出したいエンドポイントを持つ**リソース**フィールドを定義します。

完全なURLが正しく構築され、誤ったAPIリクエストが防がれるようにするため、リソースパスにスラッシュ '/' の使用に注意してください。クレデンシャルに応じて異なる場合があります。

* クレデンシャルURLがスラッシュで終わる場合は、例: `https://<インスタンス>.service-now.com/`、リソースはスラッシュなしで開始します。 例: `api/now/table/incident`
* あなたのクレデンシャルURLがスラッシュで終わらない場合、例: `https://<インスタンス>.service-now.com`、リソースはスラッシュで開始します。 例: `/api/now/table/incident`

## APIコールからデータを収集する

サービス/APIティンクレット設定から、外部システムからのAPIコールレスポンスからデータを収集するためにサポートされる**JSON解析言語**を選択します。

* **JSONata（推奨）**: これはJSONのための強力なクエリーと変換言語です。 複雑なフィルタリング、計算、データ再構築を可能にします。
* **JSONPath**: これはJSONからフィールドを抽出するためのシンプルな言語です。 これは、システムがシンプルなデータアクセスパスを期待する場合によく使用されます。

{% hint style="info" %}
サービス/APIティンクレットは、外部システムからのレスポンスを10秒まで待ち受け、以降はコールを失敗として扱います。

外部システムからのレスポンスは、サービス/APIティンクレットの出力設定に関わらず、2MBを超えてはいけません。
{% endhint %}

### 出力設定

{% hint style="warning" %}
システムは 1 Thinklet 当たり最大 5 つの出力をサポートします。

最大出力サイズは30KBまたは3,840文字です。
{% endhint %}

サービス/APIティンクレット用に[JSONの解析言語を選択した後](#collecting-data-from-api-calls)、データ出力設定を定義します。

1. **出力を追加**ボタンをクリックします。
2. 条件やティンクレット入力で使用するための参照 **名前**を提供します。
3. 選択したJSON文法を使用して、データ選択と変換のための式を定義します。

以下に、APIサンプルレスポンスからデータを抽出するための—**JSONPath**と**JSONata**の—式例を示します。

```json5
 {
  "result": { "number": "INC001" },
  "value": [
    { "displayName": "Alice", "id": 1, "number": 50 },
    { "displayName": "Bob", "id": 2, "number": 120 }
  ],
  "@meta": { "key.with.dots": "yes" }
}

```

{% hint style="warning" %}
リモートアクションから取得した出力など、JSON ペイロード内の動的な値が特に改行文字のエスケープをきちんと行い、無効な JSON やリクエストの失敗を避けることを確認してください。
{% endhint %}

<details>

<summary>出力のためのJSONPath式の例</summary>

これらの式例を使用して、APIレスポンスから特定のデータを抽出します。

| ユースケース         | 式 - JSONPatch                 | 上記のAPIサンプルレスポンスの結果       |
| -------------- | ----------------------------- | ------------------------ |
| ルート要素          | `$`                           | *(全JSON)*                |
| キーへのアクセス       | `$.result`                    | `{ "number": "INC001" }` |
| ネストされた要素へのアクセス | `$.result.number`             | `"INC001"`               |
| 最初の配列要素        | `$.value[0].displayName`      | `"Alice"`                |
| キーにおける特殊文字     | `$['@meta']['key.with.dots']` | `"yes"`                  |

</details>

<details>

<summary>出力のためのJSONata式の例</summary>

これらの式例を使用して、APIレスポンスから特定のデータを抽出します。

| ユースケース         | 式 - JSONata                               | 上記のAPIサンプルレスポンスの結果                                             |
| -------------- | ----------------------------------------- | -------------------------------------------------------------- |
| トップレベルキーへのアクセス | `結果`                                      | `{ "number": "INC001" }`                                       |
| ネストされた要素へのアクセス | `result.number`                           | `"INC001"`                                                     |
| 配列の最初のアイテム     | `value[0].displayName`                    | `"Alice"`                                                      |
| 条件によるフィルタリング   | `value[number > 100].displayName`         | `[ "Bob" ]`                                                    |
| マッピングと変換       | `value.{ "name": displayName, "id": id }` | `[ { "name": "Alice", "id": 1 }, { "name": "Bob", "id": 2 } ]` |
| 計算を実行          | `value[0].number * 100`                   | `5000`                                                         |
| 集計             | `sum(value.number)`                       | `170`                                                          |

</details>

オンラインコンバーターツールを使用して、テスト中に JSONPath または JSONata を解析します。

***

## **ペイロード内でのデータベースおよびワークフロー値の使用**

ワークフローの実行中に[収集されたデータ](#collecting-data-from-api-calls)と共に、`users`と`devices`のデータを**リソース**フィールドと**ペイロード**フィールドで参照します。

動的値の参照方法については、[パラメータおよび動的値](https://docs.nexthink.com/platform/ja/user-guide/workflows/creating-workflows/parameters-and-dynamic-values) ドキュメントを参照してください。

{% hint style="warning" %}
ワークフローの値やリモートアクションの出力をペイロードで使用する際には、文字列が有効な JSON であることを確認してください。 サービス/API Thinklet は特殊文字を自動的に**エスケープ**しません。
{% endhint %}