Skip to content

非公式本サイトは非公式の日本語ドキュメントであり、Cloudflare 公式サイトではありません。最新情報はdevelopers.cloudflare.comをご確認ください。

Workers binding

最終更新 Markdown で表示Agent セットアップ

Artifacts の Workers binding を使い、Worker から直接リポジトリの作成、インポート、確認、フォーク、削除ができます。Artifacts バインディングは、トークン管理やフォークなど、リポジトリ単位の操作ができるリポジトリハンドルを返します。

先に Namespaces を確認し、ここでバインドする名前空間名を選んでください。

バインディングを設定する

Wrangler 設定ファイルに Artifacts バインディングを追加します。

{
  "$schema": "./node_modules/wrangler/config-schema.json",
  "artifacts": [
    {
      "binding": "ARTIFACTS",
      "namespace": "default"
    }
  ]
}
[[artifacts]]
binding = "ARTIFACTS"
namespace = "default" # replace with your Artifacts namespace
# remote = true # optional: use the remote Artifacts service in local dev

npx wrangler types を実行すると、Worker の環境は次のようになります。

export interface Env {
	ARTIFACTS: Artifacts;
}

Wrangler は利用側向けに Artifacts 型を生成し、環境に直接バインドします。

名前付き Wrangler 環境では、artifacts は継承されません。必要な環境ごとにバインディングを繰り返してください。

実行時、デプロイ済みの Worker は設定したバインディングを直接使います。wrangler dev、wrangler deploy、wrangler types などのローカル Wrangler コマンドでは、先に Wrangler に認証してください。ローカルの OAuth 認証は wrangler login を参照してください。CI やヘッドレス環境は CI/CD で Wrangler を実行する を参照してください。

名前空間のメソッド

env.ARTIFACTS の名前空間メソッドで、リポジトリの作成、一覧、確認、インポート、削除ができます。

create(name, opts?)

  • name RepoName 必須
  • opts.readOnly boolean 任意
  • opts.description string 任意
  • opts.setDefaultBranch string 任意
  • 戻り値 Promise<ArtifactsCreateRepoResult>

create() は、name、remote、defaultBranch、初期トークンを含むリポジトリメタデータを返します。あとで使う場合は、これらの値を保存してください。

async function createRepo(artifacts) {
	const created = await artifacts.create("starter-repo", {
		description: "Repository for automation experiments",
		readOnly: false,
		setDefaultBranch: "main",
	});

	return {
		defaultBranch: created.defaultBranch,
		name: created.name,
		remote: created.remote,
		initialToken: created.token,
	};
}
async function createRepo(artifacts: Artifacts) {
	const created = await artifacts.create("starter-repo", {
		description: "Repository for automation experiments",
		readOnly: false,
		setDefaultBranch: "main",
	});

	return {
		defaultBranch: created.defaultBranch,
		name: created.name,
		remote: created.remote,
		initialToken: created.token,
	};
}

get(name)

  • name RepoName 必須
  • 戻り値 Promise<ArtifactsRepo>
  • リポジトリが存在しない、またはまだ準備できていない場合は例外を投げます。

get() は、既存リポジトリのハンドルを返します。ハンドルで createToken()、listTokens()、revokeToken()、fork() などの非同期メソッドを呼び出します。

async function getRepoHandle(artifacts) {
	const repo = await artifacts.get("starter-repo");
	const token = await repo.createToken("read", 3600);
	return token;
}
async function getRepoHandle(artifacts: Artifacts) {
	const repo = await artifacts.get("starter-repo");
	const token = await repo.createToken("read", 3600);
	return token;
}

list(opts?)

  • opts.limit number 任意
  • opts.cursor Cursor 任意
  • 戻り値 Promise<ArtifactsRepoListResult>
async function listRepos(artifacts) {
	const page = await artifacts.list({ limit: 10 });

	return {
		repos: page.repos.map((repo) => ({
			name: repo.name,
			status: repo.status,
		})),
		nextCursor: page.cursor ?? null,
	};
}
async function listRepos(artifacts: Artifacts) {
	const page = await artifacts.list({ limit: 10 });

	return {
		repos: page.repos.map((repo) => ({
			name: repo.name,
			status: repo.status,
		})),
		nextCursor: page.cursor ?? null,
	};
}

一覧の各リポジトリには、ready、importing、forking のいずれかの status が含まれます。

import(params)

外部の git remote からリポジトリをインポートします。

  • params.source.url string 必須 — ソースリポジトリの HTTPS URL。
  • params.source.branch string 任意 — インポートするブランチ（デフォルトは remote のデフォルトブランチ）。
  • params.source.depth number 任意 — 浅いクローンの深さ。
  • params.target.name RepoName 必須 — インポート先リポジトリの名前。
  • params.target.opts.description string 任意
  • params.target.opts.readOnly boolean 任意
  • 戻り値 Promise<ArtifactsCreateRepoResult>

import() は、name、remote、defaultBranch、初期トークンを含むリポジトリメタデータを返します。あとで使う場合は、remote と name を保存してください。

async function importFromGitHub(artifacts) {
	const imported = await artifacts.import({
		source: {
			url: "https://github.com/cloudflare/workers-sdk",
			branch: "main",
		},
		target: {
			name: "workers-sdk",
		},
	});

	return {
		name: imported.name,
		remote: imported.remote,
		token: imported.token,
	};
}
async function importFromGitHub(artifacts: Artifacts) {
	const imported = await artifacts.import({
		source: {
			url: "https://github.com/cloudflare/workers-sdk",
			branch: "main",
		},
		target: {
			name: "workers-sdk",
		},
	});

	return {
		name: imported.name,
		remote: imported.remote,
		token: imported.token,
	};
}

delete(name)

  • name RepoName 必須
  • 戻り値 Promise<boolean>
async function deleteRepo(artifacts) {
	return artifacts.delete("starter-repo");
}
async function deleteRepo(artifacts: Artifacts) {
	return artifacts.delete("starter-repo");
}

リポジトリハンドルのメソッド

await artifacts.get(name) でリポジトリハンドルを取得します。ハンドルでリポジトリの非同期メソッドを呼び出します。

createToken(scope?, ttl?)

  • scope "read" | "write" 任意（デフォルト: "write"）
  • ttl number 任意（秒）
  • 戻り値 Promise<ArtifactsCreateTokenResult>
async function mintReadToken(artifacts) {
	const repo = await artifacts.get("starter-repo");
	return repo.createToken("read", 3600);
}
async function mintReadToken(artifacts: Artifacts) {
	const repo = await artifacts.get("starter-repo");
	return repo.createToken("read", 3600);
}

create() や import() と異なり、repo.createToken() は plaintext と expiresAt を含む構造化結果を返します。plaintext は Git トークン文字列です。

listTokens()

  • 戻り値 Promise<ArtifactsTokenListResult>
async function listRepoTokens(artifacts) {
	const repo = await artifacts.get("starter-repo");
	const result = await repo.listTokens();
	return {
		total: result.total,
		tokens: result.tokens,
	};
}
async function listRepoTokens(artifacts: Artifacts) {
	const repo = await artifacts.get("starter-repo");
	const result = await repo.listTokens();
	return {
		total: result.total,
		tokens: result.tokens,
	};
}

revokeToken(tokenOrId)

  • tokenOrId string 必須
  • 戻り値 Promise<boolean>
async function revokeToken(artifacts, tokenOrId) {
	const repo = await artifacts.get("starter-repo");
	return repo.revokeToken(tokenOrId);
}
async function revokeToken(artifacts: Artifacts, tokenOrId: string) {
	const repo = await artifacts.get("starter-repo");
	return repo.revokeToken(tokenOrId);
}

fork(name, opts?)

  • name RepoName 必須
  • opts.description string 任意
  • opts.readOnly boolean 任意
  • opts.defaultBranchOnly boolean 任意
  • 戻り値 Promise<ArtifactsCreateRepoResult>

fork() は新しいリポジトリのメタデータを返します。あとで使う場合は、remote と name を保存してください。

async function forkRepo(artifacts) {
	const repo = await artifacts.get("starter-repo");
	const forked = await repo.fork("starter-repo-copy", {
		description: "Fork for testing",
		defaultBranchOnly: true,
		readOnly: false,
	});

	return forked.remote;
}
async function forkRepo(artifacts: Artifacts) {
	const repo = await artifacts.get("starter-repo");
	const forked = await repo.fork("starter-repo-copy", {
		description: "Fork for testing",
		defaultBranchOnly: true,
		readOnly: false,
	});

	return forked.remote;
}

log(opts?)

  • opts.ref string 任意 — ブランチ、タグ、またはコミットハッシュ。
  • opts.limit number 任意
  • opts.offset number 任意
  • 戻り値 Promise<ArtifactsLogResult>
async function readCommitHistory(artifacts) {
	const repo = await artifacts.get("starter-repo");
	const history = await repo.log({ ref: "main", limit: 10 });
	return history;
}
async function readCommitHistory(artifacts: Artifacts) {
	const repo = await artifacts.get("starter-repo");
	const history = await repo.log({ ref: "main", limit: 10 });
	return history;
}

readCommit(hash)

  • hash string 必須 — コミットの SHA-1 ハッシュ。
  • 戻り値 Promise<ArtifactsCommit>
async function readCommit(artifacts, hash) {
	const repo = await artifacts.get("starter-repo");
	return repo.readCommit(hash);
}
async function readCommit(artifacts: Artifacts, hash: string) {
	const repo = await artifacts.get("starter-repo");
	return repo.readCommit(hash);
}

readTree(hash)

  • hash string 必須 — ツリーの SHA-1 ハッシュ。
  • 戻り値 Promise<ArtifactsTree>
async function readTree(artifacts, hash) {
	const repo = await artifacts.get("starter-repo");
	return repo.readTree(hash);
}
async function readTree(artifacts: Artifacts, hash: string) {
	const repo = await artifacts.get("starter-repo");
	return repo.readTree(hash);
}

Worker の例

この例は、1 つの Worker ルートでバインディングのメソッドを組み合わせます。

src/index.jsjs
export default {
	async fetch(request, env) {
		const url = new URL(request.url);

		if (request.method === "POST" && url.pathname === "/repos") {
			const created = await env.ARTIFACTS.create("starter-repo");
			return Response.json({
				name: created.name,
				remote: created.remote,
			});
		}

		if (request.method === "POST" && url.pathname === "/tokens") {
			const repo = await env.ARTIFACTS.get("starter-repo");
			const token = await repo.createToken("read", 3600);
			return Response.json(token);
		}

		return Response.json(
			{ message: "Use POST /repos or POST /tokens." },
			{ status: 404 },
		);
	},
};
src/index.tsts
interface Env {
	ARTIFACTS: Artifacts;
}

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);

		if (request.method === "POST" && url.pathname === "/repos") {
			const created = await env.ARTIFACTS.create("starter-repo");
			return Response.json({
				name: created.name,
				remote: created.remote,
			});
		}

		if (request.method === "POST" && url.pathname === "/tokens") {
			const repo = await env.ARTIFACTS.get("starter-repo");
			const token = await repo.createToken("read", 3600);
			return Response.json(token);
		}

		return Response.json(
			{ message: "Use POST /repos or POST /tokens." },
			{ status: 404 },
		);
	},
} satisfies ExportedHandler<Env>;

生成される型

自分のプロジェクトで npx wrangler types を実行してください。その環境の Artifacts バインディング型は、生成された worker-configuration.d.ts を正として扱います。

次のステップ

REST API

バインディングのメソッドと、その下にある HTTP ルートを比較します。

Workers で始める

ローカル開発からデプロイまで、Worker プロジェクト全体でバインディングを使います。

Git プロトコル

標準の git-over-HTTPS クライアントで、リポジトリの remote とトークンを使います。

役に立ちましたか？