LinkedInのデータは、ブラウザ上では一貫して見えますが、その裏にあるエンティティは互いに置き換えられるものではありません。人物には職歴と学歴があり、企業には業界と所在地があり、投稿にはエンゲージメントの指標があって変化し、求人には雇用形態と応募に関するフィールドがあります。
このチュートリアルでは、SocQ LinkedIn APIの4つ(プロフィール、企業、投稿、求人)を使い、保守しやすい公開データのワークフローを構築します。URLの準備、非同期タスク、正規化されたレコード、保存、検証、更新スケジュール、責任ある利用までを扱います。
結論: 公開されているLinkedInのURLを、対応する
POST /v1/linkedin/{resource}エンドポイントに送信し、返されたタスクIDを保存して、完了するまでポーリングし、その後に正規化されたレコードを検証してアップサートします。プロフィールのURLを求人のエンドポイントに送ったり、公開されていないフィールドを空の値と見なしたりしないでください。
LinkedInの公式APIか、公開データAPIか
LinkedInの公式APIが適しているのは、メンバーがアプリケーションを承認する場合、承認済みのパートナー向け製品にアクセスできる場合、投稿の公開などの許可が必要な操作を行う場合です。公式のアクセスにはOAuthを使い、多くの権限やパートナープログラムには明示的な承認が必要です。プロフィールの結果は、メンバーのプライバシー設定や、保存に関する契約上のルールの対象にもなります。
このチュートリアルで使うSocQのエンドポイントは、公開されていることが分かっているURLを受け付け、読み取り専用のデータ取得を行います。LinkedInのメンバーとして認証することはなく、LinkedIn全体の検索、コンテンツの投稿、返されたデータを利用する権利の付与も行いません。エンドポイントを選ぶ前に、アクセス方式を決めてください。承認されたアカウント操作には公式API、範囲を絞った公開データの読み取りには、サポートされている公開データAPIを使います。
適切なLinkedInエンドポイントを選ぶ
SocQは現在、URLベースの読み取りエンドポイントを4つ提供しています。
| リソース | エンドポイント | 受け付ける公開URL | 主な用途 |
|---|---|---|---|
| Profiles | /v1/linkedin/profiles | /in/{slug} | 公開されている本人情報、役職、職歴、学歴 |
| Companies | /v1/linkedin/companies | /company/{slug} | 企業情報、Webサイト、所在地、表示されているオーディエンス |
| Posts | /v1/linkedin/posts | /posts/、/pulse/、対応する/feed/update/ | コンテンツとエンゲージメントのスナップショット |
| Jobs | /v1/linkedin/jobs | /jobs/view/{slug} | 求人の詳細、所在地、雇用形態、応募に関するフィールド |
これらはいずれも、公開データの読み取り操作です。メンバーの承認、投稿の公開、広告、そのほか許可が必要なワークフローには、LinkedInの公式プロダクトを使ってください。
入力URLを正規化して振り分ける
送信したURLは出典として保存しつつ、そのコピーを正規化してからルーティングします。
- HTTPSとLinkedInのホスト名であることを必須にする。
- トラッキング用のクエリパラメータを取り除く。
- 安全な範囲で、ロケールやモバイル用ホストの表記を統一する。
- パスからエンティティの種類を判定する。
- バッチ内で正規化済みURLの重複を排除する。
- リクエストを消費する前に、非対応のパスを拒否する。
シンプルなルーターでは、/in/をプロフィール、/company/を企業、既知の投稿パターンを投稿、/jobs/view/を求人に対応付けます。判別があいまいなURLは、推測せずにレビュー用のキューに入れてください。
プロフィール取得タスクを送信する
curl -X POST "https://api.socq.ai/v1/linkedin/profiles" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"urls": [
"https://www.linkedin.com/in/satyanadella"
]
}'
他のリソースでも、同じ形式のリクエストを使います。
curl -X POST "https://api.socq.ai/v1/linkedin/companies" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.linkedin.com/company/microsoft/"]}'
curl -X POST "https://api.socq.ai/v1/linkedin/jobs" \
-H "Authorization: Bearer $SOCQ_API_KEY" \
-H "Content-Type: application/json" \
-d '{"urls":["https://www.linkedin.com/jobs/view/software-engineer-at-microsoft-4429527118"]}'
レスポンスとして、非同期タスクが作成されます。そのIDを、社内のバッチIDと入力に紐づけて保存してください。
重複を作らずにタスクをポーリングする
curl "https://api.socq.ai/v1/tasks/$TASK_ID?limit=100" \
-H "Authorization: Bearer $SOCQ_API_KEY"
queuedとrunningは想定内の状態として扱います。指数バックオフと最大待ち時間を設定してポーリングしてください。タスクが成功したらdata.results.itemsを処理し、has_moreがtrueならnext_cursorで続けます。
ジョブの管理表には、次の項目を記録してください。
- 社内のバッチIDとSocQのタスクID。
- リソースの種類と、正規化済みの入力URL。
- 送信、最後のポーリング、完了のタイムスタンプ。
- 終了ステータスと、正規化されたエラーカテゴリ。
- 最後にコミットした結果のカーソル。
ワーカーが再起動したという理由だけで再送信しないでください。まず、保存されているタスクの状態から再開します。
4つのスキーマを理解する
すべてのレコードは、id、platform、resource、type、url、created_at、collected_at、extraといった、正規化された共通の識別フィールドを持ちます。リソース固有のフィールドは、明示的に残されます。
プロフィールには、name、description、avatar_url、表示されているフォロワーとつながりの指標に加え、役職、企業、所在地、職歴、学歴、スキルが任意でextraに含まれます。
企業には、website、ロゴ、表示されているフォロワー数と従業員数に加え、業界、規模、本社所在地、設立、拠点、専門分野が任意で追加されます。
投稿には、text、正規化されたauthor、表示されているいいね・コメント・リポストの指標、メディア、公開日時に加え、投稿タイプやハッシュタグが任意で含まれます。
求人では、nameに職種名、textに職務内容、authorに採用企業を使い、extraに所在地、職位、雇用形態、業界、応募URL、Easy Applyの状態、公開されている場合は給与が入ります。
欠けているデータは、nullのままにするか、存在しない状態のままにします。非表示のフォロワー数は0ではなく、不明な給与は無給を意味せず、取得できないタイムスタンプは取得日時ではありません。
複数種類のLinkedIn URLを処理するPythonワーカー
import time
import requests
BASE = "https://api.socq.ai/v1"
HEADERS = {
"Authorization": f"Bearer {SOCQ_API_KEY}",
"Content-Type": "application/json",
}
def collect(resource, urls):
created = requests.post(
f"{BASE}/linkedin/{resource}",
headers=HEADERS,
json={"urls": urls},
timeout=30,
)
created.raise_for_status()
task_id = created.json()["data"]["task_id"]
delay = 2
while True:
response = requests.get(
f"{BASE}/tasks/{task_id}",
headers=HEADERS,
timeout=30,
)
response.raise_for_status()
task = response.json()["data"]
if task["status"] == "succeeded":
return task["results"]["items"]
if task["status"] in {"failed", "cancelled"}:
raise RuntimeError(task)
time.sleep(delay)
delay = min(delay * 1.5, 15)
profiles = collect("profiles", [
"https://www.linkedin.com/in/satyanadella"
])
本番環境では、リトライは一時的な障害に限定し、ポーリングの前にタスクを永続化し、1回のレスポンスにバッチ全体が含まれると決めつけずに結果をページ送りで取得してください。
ソースレコードとスナップショットを分けてモデル化する
プロフィールと企業の変化はゆっくりですが、投稿の指標や求人の有効性は短時間で変わることがあります。そのため、2つのレイヤーを使います。
linkedin_entity
platform_id
resource
canonical_url
stable public fields
first_seen_at
last_seen_at
linkedin_snapshot
platform_id
collected_at
visible metrics
mutable public fields
source_task_id
IDがある場合は、resource + idでエンティティをアップサートします。ない場合は、正規化済みURLをフォールバックとして使い、後からIDが判明したときに統合できる経路を残してください。スナップショットは、取得が成功し、スキーマの検証を通過した後にのみ追記します。
求人では、first_seen_at、last_seen_at、そしてローカルで推定した有効性の状態を保持します。更新に失敗したことは、求人が終了した証拠にはなりません。
本番に読み込む前に検証する
最低限、次の点を確認してください。
platformがlinkedinと一致している。resourceが、使用したエンドポイントと一致している。- 返されたURLが、想定されるLinkedInの公開URLのパターンに従っている。
- IDとURLが、互換性のないリソースの種類間で衝突していない。
- 値が存在する場合、数値が負でない。
created_atとcollected_atがタイムスタンプとして解析できる。- 配列と入れ子のオブジェクトが、想定された型である。
- すべてのレコードを、入力とタスクまでたどれる。
無効なレコードは、黙って変換するのではなく隔離してください。生のレスポンス、検証エラー、プロバイダーのバージョン、取得日時を残しておくと、スキーマの変更を診断しやすくなります。
エンティティごとに更新スケジュールを選ぶ
すべてのエンティティを同じ頻度でスクレイピングしないでください。
| エンティティ | 開始時の適切な頻度 | 理由 |
|---|---|---|
| プロフィール | 週次または月次 | 公開されているキャリア情報の変化は比較的ゆっくり |
| 企業 | 週次または月次 | 企業情報は分単位で変わるデータではない |
| 投稿 | 稼働中は1時間〜1日ごと | 公開後はエンゲージメントが急速に変化する |
| 求人 | 募集中は毎日 | 有効性や応募の詳細が変わることがある |
ビジネス上の必要性、同意、契約上の制限、データ最小化の原則に基づいて、不要な収集を減らしてください。
LinkedInデータの責任ある利用
正当な目的に必要な公開フィールドだけを収集してください。認証、非公開プロフィール、アクセス制御、レート制限、技術的な制限を回避してはいけません。適切な保護措置なしに、個人に重大な影響を与えかねない機微な推論や自動的な意思決定を行うことは避けてください。
LinkedInのデータは個人データに該当する場合があります。必要に応じて適法な根拠を確立し、保持と削除の手順を定め、APIキーと保存したレコードを保護し、該当する権利に対応し、LinkedInの最新の利用規約と現地の法律を、資格のある法律の専門家とともに確認してください。
よくある失敗パターン
エンドポイントがアイテムを返さない
URLが公開されていて、正規化されており、まだ利用可能で、正しいエンドポイントに振り分けられているかを確認してください。入力単位のエラーは、空のレコードに変えず、そのまま保持します。
フィールドが消えた
公開の可視性やページのレンダリングは変わります。フィールドはnull許容にしておき、パーサーの変更を疑う前に、取得日時を比較してください。
同じ人物が2回表示される
URLを正規化し、安定した公開プラットフォームIDを優先してください。根拠なく片方のレコードを削除せず、エイリアスの表を管理します。
指標がブラウザの表示と一致しない
数値は取得時点のスナップショットであり、丸められたり、非表示になったり、キャッシュされたり、リクエストの間に更新されたりすることがあります。タイムスタンプとフィールドの定義を比較してください。
よくある質問(FAQ)
LinkedInのスクレイピングは合法ですか?
すべてに当てはまる答えはありません。法域、データ、アクセス方法、目的、契約、保護措置によって異なります。このチュートリアルは法的助言ではありません。
このAPIでLinkedInのすべてのプロフィールや求人を検索できますか?
現在のSocQの4つのエンドポイントは、URLベースの収集エンドポイントです。LinkedInを網羅的に検索できることは保証していません。
非公開のプロフィールをスクレイピングできますか?
いいえ。プライバシーやアクセス制御を回避してはいけません。
生のレスポンスは保存すべきですか?
はい。適切なセキュリティと保持期間を設けたうえで保存してください。変換の監査やスキーマ変更の診断に役立ちます。
重複排除にはどのキーを使うべきですか?
resource + idを優先してください。公開IDが取得できない場合は、正規化済みの正規URLにフォールバックします。