🔖

DydraへのAPI経由でのRDFデータ登録ガイド

2025/10/10に公開

はじめに

Dydraは、クラウドベースのRDFデータベースサービスで、SPARQL endpointとREST APIを提供しています。本記事では、Dydra APIを使用してプログラマティックにRDFデータを登録する方法を解説します。

前提条件

Dydraアカウント
APIキー
Node.js環境（v16以上推奨、Node.js使用時）

注意: 本記事のコード例では、サンプルとして以下を使用しています：

アカウント名: your-account
リポジトリ名: your-repository
APIキー: your_api_key_here

実際に使用する際は、ご自身のDydraアカウント情報に置き換えてください。

APIの基本情報

エンドポイント構成

ベースURL: https://dydra.com/{account}/{repository}

例: https://dydra.com/your-account/your-repository

SPARQL Query: /sparql (GET)
SPARQL Update: /sparql (POST)
Statements: /statements (POST/GET/DELETE)

認証

DydraではBearerトークン認証を使用します：

Authorization: Bearer YOUR_API_KEY

実装方法

Dydra APIへのアクセスは、curl、Python、Node.jsなど様々な方法で実装できます。それぞれの方法を紹介します。

方法1: curlでの実装（最もシンプル）

curlを使えば、プログラミング言語なしで即座にデータ登録が可能です。

基本的な認証

# APIキーを環境変数に設定
export DYDRA_API_KEY="your_api_key_here"
export DYDRA_BASE_URL="https://dydra.com/your-account/your-repository"

Turtle形式でのデータ登録

# data.ttl ファイルから登録
curl -X POST \
  -H "Authorization: Bearer ${DYDRA_API_KEY}" \
  -H "Content-Type: text/turtle" \
  --data-binary @data.ttl \
  "${DYDRA_BASE_URL}/statements"

data.ttl の例:

@prefix ex: <http://example.org/> .
@prefix dcterms: <http://purl.org/dc/terms/> .

ex:document001 a ex:Document ;
    dcterms:title "研究報告書" ;
    ex:storageLocation "osf://project/file.pdf" ;
    ex:fileSize 2048576 .

インラインデータでの登録

curl -X POST \
  -H "Authorization: Bearer ${DYDRA_API_KEY}" \
  -H "Content-Type: text/turtle" \
  --data '@prefix ex: <http://example.org/> .
ex:test001 a ex:Person ;
    ex:name "John Doe" ;
    ex:age 30 .' \
  "${DYDRA_BASE_URL}/statements"

SPARQL UPDATEでの登録

curl -X POST \
  -H "Authorization: Bearer ${DYDRA_API_KEY}" \
  -H "Content-Type: application/sparql-update" \
  --data "PREFIX ex: <http://example.org/>
PREFIX dcterms: <http://purl.org/dc/terms/>

INSERT DATA {
  GRAPH <http://example.org/documents> {
    ex:document002 a ex:Document ;
      dcterms:title \"技術文書\" ;
      ex:storageLocation \"s3://bucket/doc.pdf\" .
  }
}" \
  "${DYDRA_BASE_URL}/sparql"

SPARQLクエリの実行

# GETリクエストでクエリ
curl -G \
  -H "Authorization: Bearer ${DYDRA_API_KEY}" \
  -H "Accept: application/sparql-results+json" \
  --data-urlencode "query=SELECT * WHERE { ?s ?p ?o } LIMIT 10" \
  "${DYDRA_BASE_URL}/sparql"

データの削除

curl -X POST \
  -H "Authorization: Bearer ${DYDRA_API_KEY}" \
  -H "Content-Type: application/sparql-update" \
  --data "PREFIX ex: <http://example.org/>

DELETE WHERE {
  ex:document001 ?p ?o .
}" \
  "${DYDRA_BASE_URL}/sparql"

JSON-LD形式での登録

curl -X POST \
  -H "Authorization: Bearer ${DYDRA_API_KEY}" \
  -H "Content-Type: application/ld+json" \
  --data '{
  "@context": {
    "ex": "http://example.org/",
    "dcterms": "http://purl.org/dc/terms/"
  },
  "@id": "ex:document003",
  "@type": "ex:Document",
  "dcterms:title": "JSON-LD Document",
  "ex:fileSize": 1024000
}' \
  "${DYDRA_BASE_URL}/statements"

curlスクリプト例

複数のファイルを連続で登録するシェルスクリプト：

#!/bin/bash

DYDRA_API_KEY="your_api_key_here"
DYDRA_BASE_URL="https://dydra.com/your-account/your-repository"

# data ディレクトリ内のすべての .ttl ファイルを登録
for file in data/*.ttl; do
  echo "Uploading $file..."
  
  curl -X POST \
    -H "Authorization: Bearer ${DYDRA_API_KEY}" \
    -H "Content-Type: text/turtle" \
    --data-binary @"$file" \
    "${DYDRA_BASE_URL}/statements"
  
  if [ $? -eq 0 ]; then
    echo "✅ Successfully uploaded $file"
  else
    echo "❌ Failed to upload $file"
  fi
  
  # レート制限対策
  sleep 1
done

レスポンスの確認

# 詳細なレスポンスを表示
curl -v -X POST \
  -H "Authorization: Bearer ${DYDRA_API_KEY}" \
  -H "Content-Type: text/turtle" \
  --data-binary @data.ttl \
  "${DYDRA_BASE_URL}/statements"

# HTTPステータスコードのみを取得
curl -o /dev/null -s -w "%{http_code}\n" \
  -X POST \
  -H "Authorization: Bearer ${DYDRA_API_KEY}" \
  -H "Content-Type: text/turtle" \
  --data-binary @data.ttl \
  "${DYDRA_BASE_URL}/statements"

方法2: Pythonでの実装

import requests
import os

class DydraClient:
    def __init__(self, api_key, account, repository):
        self.api_key = api_key
        self.base_url = f"https://dydra.com/{account}/{repository}"
        self.headers = {
            "Authorization": f"Bearer {api_key}"
        }
    
    def insert_turtle(self, turtle_data):
        """Turtle形式でデータを登録"""
        response = requests.post(
            f"{self.base_url}/statements",
            data=turtle_data,
            headers={
                **self.headers,
                "Content-Type": "text/turtle"
            }
        )
        response.raise_for_status()
        return response
    
    def query(self, sparql):
        """SPARQLクエリを実行"""
        response = requests.get(
            f"{self.base_url}/sparql",
            params={"query": sparql},
            headers={
                **self.headers,
                "Accept": "application/sparql-results+json"
            }
        )
        response.raise_for_status()
        return response.json()
    
    def update(self, sparql):
        """SPARQL UPDATEを実行"""
        response = requests.post(
            f"{self.base_url}/sparql",
            data=sparql,
            headers={
                **self.headers,
                "Content-Type": "application/sparql-update"
            }
        )
        response.raise_for_status()
        return response

# 使用例
client = DydraClient(
    api_key=os.getenv("DYDRA_API_KEY"),
    account="your-account",
    repository="your-repository"
)

# データ登録
turtle = """
@prefix ex: <http://example.org/> .
ex:test a ex:Document ;
    ex:title "Test Document" .
"""
client.insert_turtle(turtle)

# クエリ実行
results = client.query("SELECT * WHERE { ?s ?p ?o } LIMIT 10")
print(results)

方法3: Node.js/TypeScriptでの実装

基本的なセットアップ

まず、必要なパッケージをインストールします：

npm install axios dotenv

環境変数ファイル（.env）にAPIキーを保存：

DYDRA_API_KEY=your_api_key_here
DYDRA_ACCOUNT=your-account
DYDRA_REPOSITORY=your-repository

Dydraクライアントクラスの実装

import axios, { AxiosInstance } from 'axios';

interface DydraConfig {
  apiKey: string;
  account: string;
  repository: string;
}

class DydraClient {
  private client: AxiosInstance;
  private baseUrl: string;

  constructor(config: DydraConfig) {
    this.baseUrl = `https://dydra.com/${config.account}/${config.repository}`;
    
    this.client = axios.create({
      baseURL: this.baseUrl,
      headers: {
        'Authorization': `Bearer ${config.apiKey}`,
      },
    });
  }

  /**
   * Turtle形式でデータを登録
   */
  async insertTurtle(turtle: string): Promise<void> {
    try {
      await this.client.post('/statements', turtle, {
        headers: { 'Content-Type': 'text/turtle' }
      });
      console.log('✅ Data inserted successfully');
    } catch (error) {
      this.handleError(error, 'insertTurtle');
    }
  }

  /**
   * SPARQL UPDATEクエリを実行
   */
  async update(sparql: string): Promise<void> {
    try {
      await this.client.post('/sparql', sparql, {
        headers: { 'Content-Type': 'application/sparql-update' }
      });
      console.log('✅ Update executed successfully');
    } catch (error) {
      this.handleError(error, 'update');
    }
  }

  /**
   * SPARQLクエリを実行
   */
  async query(sparql: string): Promise<any> {
    try {
      const response = await this.client.get('/sparql', {
        params: { query: sparql },
        headers: { 'Accept': 'application/sparql-results+json' }
      });
      return response.data;
    } catch (error) {
      this.handleError(error, 'query');
    }
  }

  /**
   * JSON-LD形式でデータを登録
   */
  async insertJSONLD(jsonld: object): Promise<void> {
    try {
      await this.client.post('/statements', jsonld, {
        headers: { 'Content-Type': 'application/ld+json' }
      });
      console.log('✅ JSON-LD inserted successfully');
    } catch (error) {
      this.handleError(error, 'insertJSONLD');
    }
  }

  /**
   * データを削除
   */
  async delete(sparql: string): Promise<void> {
    try {
      await this.client.post('/sparql', sparql, {
        headers: { 'Content-Type': 'application/sparql-update' }
      });
      console.log('✅ Data deleted successfully');
    } catch (error) {
      this.handleError(error, 'delete');
    }
  }

  private handleError(error: any, operation: string): never {
    if (axios.isAxiosError(error)) {
      const status = error.response?.status;
      const data = error.response?.data;
      
      console.error(`❌ Error in ${operation}:`);
      console.error(`   Status: ${status}`);
      console.error(`   Message: ${data}`);
      
      if (status === 401) {
        throw new Error('Authentication failed. Check your API key.');
      } else if (status === 400) {
        throw new Error(`Bad request: ${data}`);
      }
    }
    throw error;
  }
}

export default DydraClient;

Node.js使用例

基本的なデータ登録

import DydraClient from './DydraClient';
import dotenv from 'dotenv';

dotenv.config();

const client = new DydraClient({
  apiKey: process.env.DYDRA_API_KEY!,
  account: process.env.DYDRA_ACCOUNT!,
  repository: process.env.DYDRA_REPOSITORY!,
});

// Turtle形式での登録
const turtle = `
@prefix ex: <http://example.org/> .
@prefix dcterms: <http://purl.org/dc/terms/> .
@prefix xsd: <http://www.w3.org/2001/XMLSchema#> .

ex:document001 a ex:Document ;
    dcterms:title "研究報告書2025" ;
    ex:storageLocation "osf://project123/report.pdf" ;
    ex:fileSize 2048576 ;
    ex:checksum "sha256:abc123..." ;
    dcterms:created "2025-10-10T10:00:00Z"^^xsd:dateTime .
`;

await client.insertTurtle(turtle);

SPARQL UPDATEでの登録

const sparqlInsert = `
PREFIX ex: <http://example.org/>
PREFIX dcterms: <http://purl.org/dc/terms/>

INSERT DATA {
  GRAPH <http://example.org/documents> {
    ex:document002 a ex:Document ;
      dcterms:title "技術文書" ;
      ex:storageLocation "s3://bucket/tech-doc.pdf" ;
      ex:fileSize 1024000 .
  }
}
`;

await client.update(sparqlInsert);

データの検索

const results = await client.query(`
  PREFIX ex: <http://example.org/>
  PREFIX dcterms: <http://purl.org/dc/terms/>
  
  SELECT ?doc ?title ?location WHERE {
    ?doc a ex:Document ;
         dcterms:title ?title ;
         ex:storageLocation ?location .
  }
  LIMIT 10
`);

console.log(results);

各実装方法の比較

方法	メリット	デメリット	推奨用途
curl	・環境構築不要・即座に実行可能・シェルスクリプトで自動化	・複雑なロジックは困難・エラーハンドリングが弱い	・クイックテスト・単純なバッチ処理・CI/CDパイプライン
Python	・読みやすい・豊富なライブラリ・データ分析との統合	・型安全性が低い	・データ分析・スクリプト処理・機械学習との統合
Node.js/TS	・型安全性・非同期処理が得意・Web APIとの統合	・初期設定が必要	・Webアプリケーション・大規模システム・本番環境

まとめ

DydraのAPIを使用することで、RDFデータを柔軟にプログラマティックに管理できます。

実装方法の選択指針

curl（シェルスクリプト）を使うべき場合:

クイックなテストや検証
CI/CDパイプラインでの自動化
環境構築を最小限にしたい
シンプルなバッチ処理

Pythonを使うべき場合:

データ分析と連携
機械学習パイプラインとの統合
複雑なデータ変換処理
Jupyter Notebookでのプロトタイピング

Node.js/TypeScriptを使うべき場合:

Webアプリケーション開発
型安全性が重要
大規模システム
本番環境での長期運用

重要なポイント

APIキーの管理: 環境変数を使用し、コードにハードコードしない
エラーハンドリング: リトライロジックと適切なログ出力
レート制限: リクエスト間に適切な遅延を設定
バリデーション: データ登録前にRDF構文をチェック
バッチ処理: 大量データは分割して処理

次のステップ

Dydra公式ドキュメントで詳細な仕様を確認
SPARQL 1.1仕様でクエリを学習
RDF Turtle仕様でRDF記法をマスター
本記事のコードをベースに自分のユースケースに合わせてカスタマイズ

本記事で紹介したパターンを活用して、堅牢なRDFデータ管理システムを構築してください。

DydraへのAPI経由でのRDFデータ登録ガイド

はじめに

前提条件

APIの基本情報

エンドポイント構成

認証

実装方法

方法1: curlでの実装（最もシンプル）

基本的な認証

Turtle形式でのデータ登録

インラインデータでの登録

SPARQL UPDATEでの登録

SPARQLクエリの実行

データの削除

JSON-LD形式での登録

curlスクリプト例

レスポンスの確認

方法2: Pythonでの実装

方法3: Node.js/TypeScriptでの実装

基本的なセットアップ

Dydraクライアントクラスの実装

Node.js使用例

基本的なデータ登録

SPARQL UPDATEでの登録

データの検索

各実装方法の比較

まとめ

実装方法の選択指針

重要なポイント

次のステップ

参考リンク

Discussion