← Artifacts / artifacts / api

привязка Workers

Используйте binding Artifacts для Workers, чтобы создавать, импортировать, просматривать, форкать и удалять репозитории прямо из своего Worker. Binding Artifacts возвращает handle репозитория, который позволяет выполнять операции в его области действия, такие как управление токенами и форк.

Проверьте Пространства имён сначала, затем выберите имя пространства имён, которое будете привязывать здесь.

Настройка привязки

Добавьте привязку Artifacts в файл конфигурации Wrangler:

{
  "$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 не наследуется. Повторите binding в каждом окружении, где он нужен.

Во время выполнения развёрнутые Workers используют настроенную привязку напрямую. Для локальных команд Wrangler, таких как wrangler dev, wrangler deploy, или wrangler types, сначала выполните аутентификацию Wrangler. Подробнее о локальной OAuth аутентификации см. wrangler login. Для CI или headless окружений см. Запуск Wrangler в CI/CD.

Методы пространства имён

Используйте методы пространства имен для 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() возвращает handle для существующего репозитория. Используйте этот handle для вызова асинхронных методов репозитория, например 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,
	};
}

Каждый репозиторий в списке включает status значение ready, importing, или forking.

`import(params)`

Импортируйте репозиторий из внешнего git-репозитория.

params.source.url string обязательно : HTTPS URL исходного репозитория.
params.source.branch string необязательно : ветка для импорта (по умолчанию используется ветка по умолчанию удалённого репозитория).
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) чтобы получить handle репозитория. Используйте этот handle для вызова асинхронных методов репозитория.

`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

В этом примере методы binding объединены в одном маршруте Worker.

src/index.js

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.ts

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 в своём собственном проекте и рассматривайте сгенерированный worker-configuration.d.ts файл как источник истины для типов binding Artifacts в этом окружении.