# サービス/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 %}
* **名前**: サービス/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 %}
出力のためのJSONPath式の例
これらの式例を使用して、APIレスポンスから特定のデータを抽出します。
| ユースケース | 式 - JSONPatch | 上記のAPIサンプルレスポンスの結果 |
| -------------- | ----------------------------- | ------------------------ |
| ルート要素 | `$` | *(全JSON)* |
| キーへのアクセス | `$.result` | `{ "number": "INC001" }` |
| ネストされた要素へのアクセス | `$.result.number` | `"INC001"` |
| 最初の配列要素 | `$.value[0].displayName` | `"Alice"` |
| キーにおける特殊文字 | `$['@meta']['key.with.dots']` | `"yes"` |
出力のためのJSONata式の例
これらの式例を使用して、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` |
オンラインコンバーターツールを使用して、テスト中に JSONPath または JSONata を解析します。
***
## **ペイロード内でのデータベースおよびワークフロー値の使用**
ワークフローの実行中に[収集されたデータ](#collecting-data-from-api-calls)と共に、`users`と`devices`のデータを**リソース**フィールドと**ペイロード**フィールドで参照します。
動的値の参照方法については、[パラメータおよび動的値](/platform/ja/user-guide/workflows/creating-workflows/parameters-and-dynamic-values.md) ドキュメントを参照してください。
{% hint style="warning" %}
ワークフローの値やリモートアクションの出力をペイロードで使用する際には、文字列が有効な JSON であることを確認してください。 サービス/API Thinklet は特殊文字を自動的に**エスケープ**しません。
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.nexthink.com/platform/ja/user-guide/workflows/creating-workflows/configuring-thinklets/service-api-thinklet.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.