@things-factory/integration-headless 8.0.5 → 9.0.0-beta.12

package/helps/integration/connector/headless-connector.ja.md

@@ -1,57 +1,172 @@
-### ヘッドレスプールコネクタ (Headless Pool Connector)
+### 🏆 ヘッドレスコネクター (Headless Connector)
 
-**ヘッドレスプールコネクタ**は、ヘッドレスブラウザインスタンスのプールを管理するために設計されています。このコネクタは、PDFの生成やウェブスクレイピングのように、複数のヘッドレスブラウザセッションを同時に実行する必要がある作業に便利です。このコネクタは、これらのヘッドレスブラウザインスタンスの作成、使用、および破棄を効率的に管理します。
+**ヘッドレスコネクター**は、ヘッドレスブラウザを使用して **自動ログイン**、**ウェブスクレイピング**、**PDF生成**、**フォーム送信** などのタスクを実行する強力なツールです。  
+複数のブラウザセッションを管理し、セッションの維持、クッキーの処理、APIベースのログインなどに対応しています。
 
-#### エンドポイント
+---
 
-`ヘッドレスプールコネクタ`は特定のエンドポイントを要求しませんが、接続設定の一環としてURIを提供できます。このURIは通常プレースホルダーとして使用され、プールが内部的に実際の接続を処理します。つまり、エンドポイントには任意の文字列を入力することができます。
+## 🚀 1. エンドポイント (Endpoint)
 
-#### パラメータ
+**ヘッドレスコネクター**のエンドポイントは、**対象となるウェブサイトのURL** を入力します。  
+例えば、`https://example.com` を入力すると、そのウェブサイトのコンテンツを取得できます。  
+内部コンテンツからPDFを生成する場合は、`localhost` も使用できます。
 
-- **min** (数字):
-  - プール内で維持する最小のヘッドレスブラウザインスタンスの数を指定します。
-  - デフォルト値: `2`
-- **max** (数字):
-  - プールが処理できる最大のヘッドレスブラウザインスタンスの数を指定します。
-  - デフォルト値: `10`
+---
 
-これらのパラメータは、予想される作業負荷に応じてプールのサイズを調整できるようにします。例えば、アプリケーションが同時に複数のブラウザインスタンスを頻繁に必要とする場合、`max`値を増やすことができます。
+## 🔧 2. パラメーター (Parameters)
 
-#### 設定例
+### ✅ ログイン関連設定
+
+| パラメーター         | タイプ   | 説明                                            | デフォルト値  |
+| -------------------- | -------- | ----------------------------------------------- | ------------- |
+| `username`           | `string` | ログインID (ユーザー名)                         | `""`          |
+| `password`           | `string` | ログイン用パスワード                            | `""`          |
+| `loginPagePath`      | `string` | ログインページのパス (例: `/login`)             | `"/login"`    |
+| `loginApiUrl`        | `string` | ログインAPIのエンドポイント (必要な場合のみ)    | `null`        |
+| `usernameSelector`   | `string` | ユーザー名入力欄のCSSセレクター                 | `"#username"` |
+| `passwordSelector`   | `string` | パスワード入力欄のCSSセレクター                 | `"#password"` |
+| `submitSelector`     | `string` | ログインボタンのCSSセレクター                   | `"#submit"`   |
+| `successSelector`    | `string` | ログイン成功を確認するための要素のCSSセレクター | `null`        |
+| `shadowDomSelectors` | `string` | Shadow DOM 内の要素を指定 (カンマ区切り)        | `""`          |
+| `timeout`            | `number` | ログインやページ読み込みのタイムアウト時間 (ms) | `15000`       |
+| `retries`            | `number` | ログインの試行回数                              | `3`           |
+
+---
+
+## 🔍 3. `loginApiUrl` の詳細説明
+
+### 🔹 `loginApiUrl`とは？
+
+`loginApiUrl` は、ウェブサイトが **APIベースのログイン** を使用する場合に設定するパラメーターです。  
+サイトによっては、ログインページでフォーム送信する代わりに、バックエンドのAPIを直接呼び出してログインする仕組みを持っています。
+
+---
+
+### ✅ `loginApiUrl` を **設定しない場合 (`null`)**
+
+この場合、**HTMLフォームを使用したログイン方式** を採用します。  
+ヘッドレスブラウザが自動的にユーザー名とパスワードを入力し、フォームを送信します。
+
+#### 📌 例 (HTMLフォームログイン)
+
+```json
+{
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+#### 🛠 動作の流れ:
+
+1. `https://example.com/login` に移動
+2. `#username` と `#password` にログイン情報を入力
+3. `#submit-button` をクリックしてフォーム送信
+4. `.dashboard` 要素の有無でログイン成功を判断
+
+---
+
+### ✅ `loginApiUrl` を **設定する場合**
+
+この場合、サイトが **APIベースの認証** を使用しているため、`loginApiUrl` を明示的に設定する必要があります。  
+例えば、ログインAPIが `/api/auth/login` の場合、このURLを指定します。
+
+#### 📌 例 (APIベースのログイン)
+
+```json
+{
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+#### 🛠 動作の流れ:
+
+1. `https://example.com/api/auth/login` に **POSTリクエスト** を送信
+2. サーバーからレスポンスを受け取り、セッションのクッキーを保存
+3. メインページへ移動し、`.dashboard` の存在を確認
+
+---
+
+## 🏗 4. 設定例
 
 ```json
 {
-  "name": "headless-browser-pool",
+  "name": "headless-browser-connector",
   "connector": "headless-connector",
-  "endpoint": "1",
+  "endpoint": "https://example.com",
   "params": {
-    "min": 5,
-    "max": 20
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit",
+    "successSelector": ".dashboard",
+    "timeout": 20000,
+    "retries": 5
   }
 }
 ```
 
-上記の例では、プールは少なくとも5つのヘッドレスブラウザインスタンスを維持し、必要に応じて最大20インスタンスまで拡張することができます。
+---
+
+## 🔄 5. 接続のライフサイクル (Connection Lifecycle)
 
-#### 接続ライフサイクル
+- **connect**
 
-- **connect**:
+  - 設定に従ってログインを試みます。
+  - セッションを維持し、クッキーを保存して後続のリクエストで再利用します。
 
-  - 接続を初期化し、設定されたパラメータ(`min`および`max`)に従ってヘッドレスブラウザインスタンスのプールを作成します。
-  - プールはこれらのインスタンスのライフサイクルを自動的に管理し、必要に応じて新しいインスタンスを作成し、既存のインスタンスを再利用します。
+- **disconnect**
+  - ヘッドレスブラウザのセッションを終了し、クッキーをクリアします。
 
-- **disconnect**:
-  - ヘッドレスブラウザプールを破棄し、すべてのインスタンスが適切に終了し、リソースが解放されるようにします。
+---
 
-#### 使用シナリオ
+## ⚡ 6. 対応するタスク (Supported Tasks)
 
-`ヘッドレスプールコネクタ`は、ヘッドレスブラウザ環境で作業を実行する必要があるシナリオで主に使用されます。例えば、HTMLコンテンツからPDFを生成したり、ウェブページのスクリーンショットをキャプチャしたり、ウェブサイトからデータをスクレイピングする際に便利です。
+| タスクタイプ           | 説明                                   |
+| ---------------------- | -------------------------------------- |
+| `headless-pdf-capture` | HTMLをPDFに変換する                    |
+| `headless-scrap`       | ウェブページから特定データを抽出する   |
+| `headless-post`        | フォーム入力を自動化し、送信を実行する |
 
-#### サポートするタスク
+#### 📌 タスク例
 
-`ヘッドレスプールコネクタ`は `headless-pdf` プレフィックスの付いたタスクをサポートします。これらのタスクは、このコネクタが管理するヘッドレスブラウザインスタンスを使用します。
+### 1️⃣ ウェブスクレイピング (`headless-scrap`)
+
+```json
+{
+  "name": "scrape-data",
+  "taskType": "headless-scrap",
+  "params": {
+    "path": "/products",
+    "selectors": [
+      { "text": "商品名", "value": ".product-title" },
+      { "text": "価格", "value": ".product-price" }
+    ]
+  }
+}
+```
 
-#### タスクでの使用例
+### 2️⃣ PDF生成 (`headless-pdf-capture`)
 
 ```json
 {
@@ -66,6 +181,43 @@
 }
 ```
 
-#### 説明
+### 3️⃣ フォーム送信 (`headless-post`)
+
+```json
+{
+  "name": "submit-form",
+  "taskType": "headless-post",
+  "params": {
+    "formPath": "/contact",
+    "fields": {
+      "#name": "田中 太郎",
+      "#email": "tanaka@example.com",
+      "#message": "こんにちは、これはテストメッセージです！"
+    },
+    "submitSelector": "#submit-button"
+  }
+}
+```
+
+---
+
+## 📢 7. 説明 (Description)
+
+**ヘッドレスコネクター** は **ウェブスクレイピング、自動ログイン、PDF生成、フォーム送信** などを  
+効率的に実行するための強力なツールです。  
+**HTMLベースのログイン** と **APIベースのログイン** の両方に対応し、さまざまなサイトでの認証処理が可能です。
+
+---
+
+### 📌 まとめ
+
+| 機能                     | 説明                                   |
+| ------------------------ | -------------------------------------- |
+| **HTMLフォームログイン** | ユーザー操作をシミュレートしてログイン |
+| **APIログイン**          | APIリクエストで直接ログイン (高速)     |
+| **セッション管理**       | クッキーを保存し、セッションを維持     |
+| **ウェブスクレイピング** | 指定したコンテンツを抽出して取得       |
+| **PDF変換**              | HTMLページをPDFに変換                  |
+| **フォーム送信**         | 自動的にフォーム入力＆送信を実行       |
 
-**ヘッドレスプールコネクタ**は、PDF生成やウェブスクレイピングなどの作業を効率的に実行するために、ヘッドレスブラウザインスタンスのプールを管理し、高負荷なシナリオでのリソース利用の最適化と拡張性を保証します。
+📌 **ヘッドレスコネクターを使えば、さまざまなウェブサイトのタスクを自動化できます！** 🚀

package/helps/integration/connector/headless-connector.ko.md

@@ -1,58 +1,166 @@
-### 헤드리스 풀 커넥터 (Headless Pool Connector)
+### 🏆 헤드리스 커넥터 (Headless Connector)
 
-**헤드리스 풀 커넥터**는 헤드리스 브라우저 인스턴스의 풀(pool)을 관리하기 위해 설계되었습니다. 이 커넥터는 PDF 생성이나 웹 스크래핑과 같이 여러 개의 헤드리스 브라우저 세션이 동시에 필요한 작업을 수행할 때 유용합니다. 이 커넥터는 이 헤드리스 브라우저 인스턴스의 생성, 사용 및 파기를 효율적으로 관리합니다.
+**헤드리스 커넥터**는 헤드리스 브라우저를 활용하여 **로그인 자동화**, **웹 스크래핑**, **PDF 생성**, **폼 제출** 등의 작업을 수행하는 강력한 커넥터입니다.  
+여러 개의 브라우저 세션을 관리하며, 세션 유지, 쿠키 활용, API 기반 로그인 등 다양한 기능을 제공합니다.
 
-#### 엔드포인트
+---
 
-`헤드리스 풀 커넥터`는 특정 엔드포인트를 요구하지 않지만, 연결 설정의 일환으로 URI를 제공할 수 있습니다. 이 URI는 일반적으로 플레이스홀더로 사용되며, 풀은 내부적으로 실제 연결을 처리합니다.
-즉, 엔트포인트는 임의의 문자열을 입력하시면 됩니다.
+## 🚀 1. 엔드포인트 (Endpoint)
 
-#### 매개변수
+헤드리스 커넥터의 엔드포인트는 **스크래핑 대상 웹사이트의 URL**을 입력합니다.  
+예를 들어, `https://example.com`과 같은 웹사이트의 내용을 가져오거나 내부 컨텐츠로 PDF 파일을 생성하려면 `localhost`를 사용할 수도 있습니다.
 
-- **min** (숫자):
-  - 풀에서 유지할 최소 헤드리스 브라우저 인스턴스 수를 지정합니다.
-  - 기본값: `2`
-- **max** (숫자):
-  - 풀이 처리할 수 있는 최대 헤드리스 브라우저 인스턴스 수를 지정합니다.
-  - 기본값: `10`
+---
 
-이 매개변수들은 예상되는 작업 부하에 맞춰 풀 크기를 조정할 수 있게 해줍니다. 예를 들어, 애플리케이션에서 여러 브라우저 인스턴스를 자주 동시에 필요로 하는 경우 `max` 값을 늘릴 수 있습니다.
+## 🔧 2. 매개변수 (Parameters)
 
-#### 설정 예시
+### ✅ 로그인 관련 설정
+
+| 매개변수             | 타입     | 설명                                                            | 기본값        |
+| -------------------- | -------- | --------------------------------------------------------------- | ------------- |
+| `username`           | `string` | 로그인할 사용자 이름 (아이디)                                   | `""`          |
+| `password`           | `string` | 로그인 비밀번호                                                 | `""`          |
+| `loginPagePath`      | `string` | 로그인 페이지의 경로 (예: `/login`)                             | `"/login"`    |
+| `loginApiUrl`        | `string` | 로그인 API 엔드포인트 (없으면 `null`)                           | `null`        |
+| `usernameSelector`   | `string` | 로그인 폼의 사용자명 입력 필드 CSS 선택자                       | `"#username"` |
+| `passwordSelector`   | `string` | 로그인 폼의 비밀번호 입력 필드 CSS 선택자                       | `"#password"` |
+| `submitSelector`     | `string` | 로그인 버튼의 CSS 선택자                                        | `"#submit"`   |
+| `successSelector`    | `string` | 로그인 성공을 판별할 수 있는 요소의 CSS 선택자                  | `null`        |
+| `shadowDomSelectors` | `string` | Shadow DOM 내부 요소를 찾을 때 사용 (쉼표로 구분된 선택자 목록) | `""`          |
+| `timeout`            | `number` | 로그인 및 페이지 로딩 대기 시간 (ms)                            | `15000`       |
+| `retries`            | `number` | 로그인 시도 횟수                                                | `3`           |
+
+---
+
+## 🔍 3. `loginApiUrl` 매개변수에 대한 상세 설명
+
+### 🔹 `loginApiUrl`란?
+
+`loginApiUrl`은 웹사이트에서 구현한 로그인 방식에 따라 로그인 시도 결과를 확인하기 위해 참고하는 설정 정보입니다.
+
+### ✅ `loginApiUrl`이 **설정되지 않은 경우 (`null`)**
+
+**HTML 폼을 통한 로그인 방식**을 사용하는 웹사이트에서는 별도로 설정하지 않아도 됩니다. 이 경우는 페이지내의 form action을 직접 참조합니다.
+
+1. `loginPagePath`에 지정된 로그인 페이지로 이동합니다.
+2. 사용자명 및 비밀번호 입력 필드에 값을 입력합니다.
+3. 로그인 버튼을 클릭하여 로그인을 시도합니다.
+4. `successSelector`를 사용해 로그인 성공 여부를 판별합니다.
+
+#### 📌 예제 설정 (HTML 폼 로그인)
+
+```json
+{
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+#### 🛠 동작 과정
+
+1. `https://example.com/login` 페이지로 이동
+2. `#username`, `#password` 입력 필드에 값을 입력
+3. `#submit-button`을 클릭하여 로그인 요청 전송
+4. `.dashboard` 요소가 나타나면 로그인 성공으로 판단
+
+---
+
+### ✅ `loginApiUrl`을 **설정하는 경우**
+
+웹사이트가 **API 기반 로그인 방식**을 사용하는 경우입니다. 이 경우 로그인을 위해서 호출되는 `loginApiUrl`을 직접 파악해서 설정해주어야 합니다.
+Origin 서버가 아닌 별도의 SSO 서버의 API를 호출하는 경우에는 전체 API URL을 설정해주면 됩니다.
+
+#### 📌 예제 설정 (API 로그인 방식의 웹사이트)
+
+```json
+{
+  "endpoint": "https://example.com",
+  "params": {
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit-button",
+    "successSelector": ".dashboard"
+  }
+}
+```
+
+---
+
+## 🏗 4. 설정 예시
 
 ```json
 {
-  "name": "headless-browser-pool",
+  "name": "headless-browser-connector",
   "connector": "headless-connector",
-  "endpoint": "1",
+  "endpoint": "https://example.com",
   "params": {
-    "min": 5,
-    "max": 20
+    "username": "user123",
+    "password": "securepassword",
+    "loginPagePath": "/login",
+    "loginApiUrl": "/api/auth/login",
+    "usernameSelector": "#username",
+    "passwordSelector": "#password",
+    "submitSelector": "#submit",
+    "successSelector": ".dashboard",
+    "timeout": 20000,
+    "retries": 5
   }
 }
 ```
 
-위 예시에서 풀은 최소 5개의 헤드리스 브라우저 인스턴스를 유지하며, 필요에 따라 최대 20개의 인스턴스로 확장할 수 있습니다.
+---
+
+## 🔄 5. 연결 생명주기 (Connection Lifecycle)
+
+- **connect**
 
-#### 연결 생명주기
+  - 설정된 매개변수에 따라 로그인 프로세스를 수행합니다.
+  - 세션이 유지되며, 쿠키를 저장하여 이후 요청에서 재사용합니다.
 
-- **connect**:
+- **disconnect**
+  - 헤드리스 브라우저 세션을 종료하고 쿠키를 정리합니다.
 
-  - 연결을 초기화하여 설정된 매개변수(`min` 및 `max`)에 따라 헤드리스 브라우저 인스턴스 풀을 생성합니다.
-  - 풀은 이러한 인스턴스들의 생명주기를 자동으로 관리하며, 필요한 경우 새로운 인스턴스를 생성하고 기존 인스턴스를 재사용합니다.
+---
 
-- **disconnect**:
-  - 헤드리스 브라우저 풀을 파기하여 모든 인스턴스가 적절히 종료되고 리소스가 해제되도록 합니다.
+## ⚡ 6. 지원하는 작업 (Supported Tasks)
 
-#### 사용 시나리오
+| 작업 유형              | 설명                                                     |
+| ---------------------- | -------------------------------------------------------- |
+| `headless-pdf-capture` | HTML을 PDF로 변환하는 작업                               |
+| `headless-scrap`       | 웹 페이지에서 특정 데이터를 추출하는 스크래핑 작업       |
+| `headless-post`        | 웹사이트에서 폼 데이터를 자동으로 입력하고 제출하는 작업 |
 
-`헤드리스 풀 커넥터`는 헤드리스 브라우저 환경에서 작업을 수행해야 하는 시나리오에서 주로 사용됩니다. 예를 들어, HTML 콘텐츠로부터 PDF를 생성하거나, 웹 페이지의 스크린샷을 캡처하거나, 웹사이트에서 데이터를 스크래핑할 때 유용합니다.
+#### 📌 작업 예시
 
-#### 지원하는 작업
+### 1️⃣ 웹 스크래핑 (`headless-scrap`)
 
-`헤드리스 풀 커넥터`는 `headless-pdf` 접두사가 붙은 작업을 지원합니다. 이러한 작업은 이 커넥터가 관리하는 헤드리스 브라우저 인스턴스를 사용하게 됩니다.
+```json
+{
+  "name": "scrape-data",
+  "taskType": "headless-scrap",
+  "params": {
+    "path": "/products",
+    "selectors": [
+      { "text": "Product Name", "value": ".product-title" },
+      { "text": "Price", "value": ".product-price" }
+    ]
+  }
+}
+```
 
-#### 작업에서의 예시 사용
+### 2️⃣ PDF 생성 (`headless-pdf-capture`)
 
 ```json
 {
@@ -67,6 +175,43 @@
 }
 ```
 
-#### 설명
+### 3️⃣ 폼 제출 (`headless-post`)
+
+```json
+{
+  "name": "submit-form",
+  "taskType": "headless-post",
+  "params": {
+    "formPath": "/contact",
+    "fields": {
+      "#name": "John Doe",
+      "#email": "john@example.com",
+      "#message": "Hello, this is a test message!"
+    },
+    "submitSelector": "#submit-button"
+  }
+}
+```
+
+---
+
+## 📢 7. 설명 (Description)
+
+**헤드리스 커넥터**는 **웹 자동화 및 스크래핑, PDF 생성, 폼 자동 입력 및 제출** 등을 위해  
+헤드리스 브라우저 세션을 관리하는 강력한 도구입니다.  
+특히 **HTML 로그인 방식**과 **API 로그인 방식**을 모두 지원하여 다양한 웹사이트에서 안정적인 로그인을 수행할 수 있습니다.
+
+---
+
+### 📌 요약
+
+| 기능            | 설명                                  |
+| --------------- | ------------------------------------- |
+| **폼 로그인**   | UI를 직접 조작하여 로그인 (HTML 기반) |
+| **API 로그인**  | HTTP 요청을 통해 직접 로그인 (빠름)   |
+| **세션 유지**   | 쿠키를 저장하여 지속적인 세션 유지    |
+| **웹 스크래핑** | 데이터 추출 및 자동화 작업 가능       |
+| **PDF 변환**    | HTML을 PDF로 변환                     |
+| **폼 제출**     | 자동으로 데이터를 입력하고 제출       |
 
-**헤드리스 풀 커넥터**는 PDF 생성 및 웹 스크래핑과 같은 작업을 수행하기 위해 헤드리스 브라우저 인스턴스 풀을 효율적으로 관리하며, 높은 수요가 있는 시나리오에서 자원 활용의 최적화와 확장성을 보장합니다.
+**이 커넥터를 활용하면 다양한 웹사이트에서 자동 로그인 및 데이터 수집을 효율적으로 수행할 수 있습니다.** 🚀