ノート: Content Attachments APIは現在パブリックベータであり、GitHub Appsと合わせてのみ利用できます。 この期間中、機能や要件はいつでも変更されることがあります。
添付コンテンツについて
GitHub Appは、content_reference
イベントをトリガーするドメインを登録できます。 Issueまたはプルリクエストの、ボディまたはコメントに、登録されたドメインにリンクするURLが含まれている� �合、アプリケーションはcontent_reference
webhookを受け取ります。 添付コンテンツを使用して、Issueまたはプルリクエストに追� したURLについてのコンテキストやデータを視覚的に追� できます。 URLは、http://
またはhttps://
から始まる、完全修飾URLである必要があります。 Markdownリンクの一部であるURLは無視され、content_reference
イベントをトリガーしません。
Content Attachments APIを使用する前に、以下を行ってGitHub Appのコンテンツ参照を設定する必要があります。
- アプリケーションに、[Content references] に対する
Read & write
権限を付与します。 - [Content references] 権限を設定する際に、一般にアクセス可能なドメインを5つまで登録します。 コンテンツ参照ドメインを設定する際は、IPアドレスは使用しないでく� さい。 ドメイン名 (example.com) またはサブドメイン (subdomain.example.com) を登録できます。
- アプリケーションを [Content reference] イベントにサブスクライブします。
アプリケーションがリポジトリにインストールされると、登録されたドメインへのURLが含まれるIssueまたはプルリクエストのコメントでは、コンテンツ参照イベントが生成されます。 アプリケーションは、コンテンツ参照URLがポストされてから6時間以内に添付コンテンツを作成しなければなりません。
添付コンテンツが、URLを遡って更新することはありません。 上記でまとめた要件に従ってアプリケーションを設定した後に、ユーザがリポジトリにアプリケーションをインストールしてから、Issueまたはプルリクエストに追� したURLに対してのみ機能します。
GitHub App の権限やイベントのサブスクリプションを設定するために必要なステップに関する詳しい情� �については、「<GitHub App を作成する」または「GitHub App の権限を編集する」を参照してく� さい。
添付コンテンツフローを実装する
添付コンテンツのフローは、IssueもしくはPull Request中のURL、content_reference
webhookイベント、追� 情� �でIssueもしくはPull Requestを更新するために呼ぶ必要があるREST APIエンドポイント間の関係を示します。
ステップ 1. 添付コンテンツについてに記載されているガイドラインに従ってアプリケーションを設定します。 添付コンテンツを使い始めるには、Probotアプリケーションのサンプルを使うこともできます。
ステップ2。IssueもしくはPull Requestに登録したドメインのURLを追� します。 http://
もしくはhttps://
で始まる完全修飾URLを使わなければなりません。
ステップ3。アプリケーションはcreated
アクション付きでcontent_reference
webhookを受信します。
{
"action": "created",
"content_reference": {
"id": 17,
"node_id": "MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA5",
"reference": "errors.ai"
},
"repository": {
"full_name": "Codertocat/Hello-World",
},
"sender": {...},
"installation": {
"id": 371641,
"node_id": "MDIzOkludGVncmF0aW9uSW5zdGFsbGF0aW9uMzcxNjQx"
}
}
ステップ4。アプリケーションはREST APIを使って添付コンテンツを作成するためにcontent_reference
id
とrepository
full_name
フィールドを使います。 GitHub Appのインストールとして認証を受けるために、installation
id
も必要になります。
ノート: プレビュー期間中にContent Attachments APIにアクセスするには、カスタ� のメディアタイプをAccept
ヘッダに渡さなければなりません。
application/vnd.github.corsair-preview+json
警告: このAPIは、プレビュー期間に予告なく変更されることがあります。 プレビューの機能は、実稼働環境での利用はサポートされていません。 問題があった� �合には、your site administratorにお問い合わせく� さい。
body
パラメータにはMarkdownが含まれていることがあります。
curl -X POST \
http(s)://[hostname]/api/v3/repos/Codertocat/Hello-World/content_references/17/attachments \
-H 'Accept: application/vnd.github.corsair-preview+json' \
-H 'Authorization: Bearer $INSTALLATION_TOKEN' \
-d '{
"title": "[A-1234] Error found in core/models.py file",
"body": "You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\n self.save()"
}'
インストールトークンの作成に関する詳しい情� �については「GitHub Appとして認証する」を参照してく� さい。
ステップ5。 Pull RequestもしくはIssueコメント内のリンクの下に、新しい添付コンテンツが表示されます。
GraphQLでの添付コンテンツの利用
content_reference
webhookイベント中でnode_id
を提供しているので、GraphQL APIのcreateContentAttachment
ミューテーションを参照できます。
ノート: プレビュー期間中にContent Attachments APIにアクセスするには、カスタ� のメディアタイプをAccept
ヘッダに渡さなければなりません。
application/vnd.github.corsair-preview+json
警告: このAPIは、プレビュー期間に予告なく変更されることがあります。 プレビューの機能は、実稼働環境での利用はサポートされていません。 問題があった� �合には、your site administratorにお問い合わせく� さい。
例:
mutation {
createContentAttachment(input: {
contentReferenceId: "MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA1",
title: "[A-1234] Error found in core/models.py file",
body:"You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\n self.save()"
}) {
contentAttachment {
... on ContentAttachment {
id
title
body
}
}
}
}
cURLの例:
curl -X "POST" "http(s)://[hostname]/api/v3/graphql" \
-H 'Authorization: Bearer $INSTALLATION_TOKEN' \
-H 'Accept: application/vnd.github.corsair-preview+json' \
-H 'Content-Type: application/json; charset=utf-8' \
-d $'{
"query": "mutation {\\n createContentAttachment(input:{contentReferenceId: \\"MDE2OkNvbnRlbnRSZWZlcmVuY2UxNjA1\\", title:\\"[A-1234] Error found in core/models.py file\\", body:\\"You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\n\self.save()\\"}) {\\n contentAttachment {\\n id,\\n title,\\n body\\n }\\n }\\n}"
}'
node_id
の詳しい情� �については「グローバルノードIDの利用」を参照してく� さい。
ProbotとGitHub Appマニフェストの利用例
Content Attachments APIを使用できるGitHub Appを手早くセットアップするには、Probotが利用できます。 ProbotがどのようにGitHub Appのマニフェストを使用するかを学ぶには、「マニフェストからのGitHub Appの作成」を参照してく� さい。
Probotアプリケーションを作成するには、以下のステップに従ってく� さい。
-
作成したプロジェクトを開き、
app.yml
ファイルの設定をカスタマイズします。content_reference
イベントをサブスクライブし、content_references
の書き込み権限を有効化してく� さい。default_events: - content_reference # GitHub Appが必要とする権限セット。 このオブジェクトのフォーマットは、 # キーの権限名(たとえばissues)と値のためのアクセスの # 種類(たとえばwrite)を使います。 # 取り得る値は `read`、`write`、`none` default_permissions: content_references: write content_references: - type: domain value: errors.ai - type: domain value: example.org
-
このコードを
index.js
ファイルに追� して、content_reference
を処理してREST APIを呼ぶようにします。module.exports = app => { // ここにコードを書く app.log('Yay, the app was loaded!') app.on('content_reference.created', async context => { console.log('Content reference created!', context.payload) // Call the "Create a content reference" REST endpoint await context.github.request({ method: 'POST', headers: { accept: 'application/vnd.github.corsair-preview+json' }, url: `/repos/${context.payload.repository.full_name}/content_references/${context.payload.content_reference.id}/attachments`, // Parameters title: '[A-1234] Error found in core/models.py file', body: 'You have used an email that already exists for the user_email_uniq field.\n ## DETAILS:\n\nThe (email)=(Octocat@github.com) already exists.\n\n The error was found in core/models.py in get_or_create_user at line 62.\n\nself.save()' }) }) }
-
GitHub Appをローカルで動作させます。
http://localhost:3000
にアクセスして、Register GitHub Appボタンをクリックしてく� さい。 -
テストリポジトリにアプリケーションをインストールしてく� さい。
-
テストリポジトリでIssueを作成してく� さい。
-
オープンしたIssueに
app.yml
ファイルで設定したURLを含むコメントを追� してく� さい。 -
Issueのコメントを見ると、以下のように更新されています。