octokit.js

Octokit.js

Github SDK من جميع الهراءات للمستعرضات ، Node.js ، و Deno.

تدمج حزمة octokit مكتبات Octokit الرئيسية الثلاث

1. عميل API (طلبات REST API ، استعلامات API GraphQL ، المصادقة)
2. عميل التطبيق (تطبيق GitHub وتثبيتات WebHooks ، OAUTH)
3. عميل الإجراء (عميل واجهة برمجة التطبيقات المسلحة مسبقًا لمستودع واحد)

جدول المحتويات

• Octokit.js
  • سمات
  • الاستخدام
  • عميل Octokit API
    • خيارات مُنشئ
    • المصادقة
    • خوادم الوكيل (node.js فقط)
      • جلب مفقود
    • استراحة API
      • octokit.rest أساليب نقطة النهاية
      • octokit.request()
      • ترقيم الصفحات
      • تنسيقات نوع الوسائط
      • طلب معالجة الخطأ
    • استعلامات API GraphQL
      • ترقيم الصفحات
      • معاينات المخطط
  • عميل التطبيق
    • تطبيق جيثب
    • Webhooks
    • Oauth
    • خادم التطبيق
    • OAUTH لتطبيقات المتصفح
  • عميل الإجراء
  • رخصة

سمات

• مكتمل . يتم تغطية جميع ميزات واجهات برمجة تطبيقات منصة Github.
• الإلزام . يتم تنفيذ جميع أفضل الممارسات الموصى بها.
• عالمي . يعمل في جميع المتصفحات الحديثة ، Node.js ، و Deno.
• تم اختباره . جميع المكتبات لديها تغطية اختبار 100 ٪.
• مطبوع . تحتوي جميع المكتبات على إعلانات TypeScript واسعة النطاق.
• التحلل . استخدم الرمز الذي تحتاجه فقط. يمكنك إنشاء Octokit الخاص بك في بضعة أسطر فقط من التعليمات البرمجية أو استخدام الطرق الثابتة الأساسية. اصنع المفاضلة الخاصة بك بين الوظيفة وحجم الحزمة.
• قابل للتمديد . ميزة مفقودة؟ أضف وظائف مع الإضافات ، أو توصيل بطلب أو دورة حياة Webhook أو تنفيذ استراتيجية المصادقة الخاصة بك.

الاستخدام

المتصفحات	تحميل octokit مباشرة من esm.sh < script type =" module " > import { Octokit , App } from "https://esm.sh/octokit" ; </ script >
دنو	تحميل octokit مباشرة من esm.sh import { Octokit , App } from "https://esm.sh/octokit?dts" ;
العقدة	تثبيت مع npm/pnpm install octokit ، أو yarn add octokit import { Octokit , App } from "octokit" ;

مهم

أثناء استخدامنا للتصدير الشرطي ، ستحتاج إلى تكييف tsconfig.json عن طريق تعيين "moduleResolution": "node16", "module": "node16" .

راجع مستندات TypeScript على package.json "الصادرات".
شاهد هذا الدليل المفيد للانتقال إلى ESM من sindresorhus

عميل Octokit API

مستقل الحد الأدنى الأوكتوكيت : @octokit/core .

يمكن استخدام عميل Octokit لإرسال طلبات إلى واجهة برمجة تطبيقات REST الخاصة بـ Github والاستعلامات إلى واجهة برمجة تطبيقات Github's GraphQL.

مثال : احصل على اسم المستخدم للمستخدم المصادق عليه.

 // Create a personal access token at https://github.com/settings/tokens/new?scopes=repo
const octokit = new Octokit ( { auth : `personal-access-token123` } ) ;

// Compare: https://docs.github.com/en/rest/reference/users#get-the-authenticated-user
const {
  data : { login } ,
} = await octokit . rest . users . getAuthenticated ( ) ;
console . log ( "Hello, %s" , login ) ;

خيارات مُنشئ

الخيارات الأكثر استخدامًا هي

اسم	يكتب	وصف
userAgent	String	يعد إعداد وكيل المستخدم مطلوبًا لجميع الطلبات المرسلة إلى واجهات برمجة تطبيقات نظام Github. يضعف وكيل المستخدم الافتراضي إلى شيء من هذا القبيل: octokit.js/v1.2.3 Node.js/v8.9.4 (macOS High Sierra; x64) . يوصي بتعيين وكيل المستخدم الخاص بك ، والذي سيقدم الإعداد الافتراضي. const octokit = new Octokit ( { userAgent : "my-app/v1.2.3" , } ) ;
authStrategy	Function	الإعدادات الافتراضية إلى @octokit/auth-token . انظر المصادقة أدناه.
auth	String أو Object	قم بتعيين رمز الوصول الشخصي إلا إذا قمت بتغيير خيار authStrategy . انظر المصادقة أدناه.
baseUrl	String	عند استخدام خادم GitHub Enterprise ، قم بتعيين options.baseUrl إلى عنوان URL الجذر الخاص بأبودي الأبراج. على سبيل المثال ، إذا كان اسم المضيف الخاص بـ GitHub Enterprise Server هو github.acme-inc.com ، ثم قم بتعيين options.baseUrl على https://github.acme-inc.com/api/v3 . مثال const octokit = new Octokit ( { baseUrl : "https://github.acme-inc.com/api/v3" , } ) ;

خيارات متقدمة

اسم	يكتب	وصف
request	Object	request.signal : استخدم مثيل AbortController لإلغاء طلب. abort-controller هو تطبيق للعقدة. request.fetch : استبدال طريقة الجلب المدمجة. العقدة فقط request.timeout يعين مهلة طلب ، الافتراضيات إلى 0 يمكن أيضًا تعيين خيار request على أساس كل شيء.
timeZone	String	يعين رأس Time-Zone التي تحدد المنطقة الزمنية وفقًا لقائمة الأسماء من قاعدة بيانات Olson. const octokit = new Octokit ( { timeZone : "America/Los_Angeles" , } ) ; سيحدد رأس المنطقة الزمنية المنطقة الزمنية المستخدمة لإنشاء الطابع الزمني عند إنشاء الارتباط. انظر وثائق Github الزمنية.
throttle	Object	Octokit ينفذ طلب الاختناق باستخدام @octokit/plugin-throttling افتراضيًا ، يتم إعادة إعادة تجهيز الطلبات مرة واحدة ويتم تسجيل التحذيرات في حالة ضرب معدل أو حد ثانوي. { onRateLimit : ( retryAfter , options , octokit ) => { octokit . log . warn ( `Request quota exhausted for request ${ options . method } ${ options . url } ` ) ; if ( options . request . retryCount === 0 ) { // only retries once octokit . log . info ( `Retrying after ${ retryAfter } seconds!` ) ; return true ; } } , onSecondaryRateLimit : ( retryAfter , options , octokit ) => { octokit . log . warn ( `SecondaryRateLimit detected for request ${ options . method } ${ options . url } ` ) ; if ( options . request . retryCount === 0 ) { // only retries once octokit . log . info ( `Retrying after ${ retryAfter } seconds!` ) ; return true ; } } , } ; لإلغاء الاشتراك في هذه الميزة: new Octokit ( { throttle : { enabled : false } } ) ; يتم دعم الخنق في مجموعة باستخدام الواجهة الخلفية Redis. انظر @octokit/plugin-throttling Clustering
retry	Object	يطبق Octokit إعادة إعادة محاكمة باستخدام @octokit/plugin-retry لإلغاء الاشتراك في هذه الميزة: new Octokit ( { retry : { enabled : false } } ) ;

المصادقة

بشكل افتراضي ، يدعم عميل Octokit API المصادقة باستخدام رمز ثابت.

هناك وسائل مختلفة للمصادقة التي يدعمها Github ، والتي يتم وصفها بالتفصيل في اختلاف Octokit/Authentication.js. يمكنك تعيين كل واحد منهم كخيار منشئ authStrategy ، وتمرير خيارات الاستراتيجية كخيار مُنشئ auth .

على سبيل المثال ، من أجل المصادقة على أنها تثبيت تطبيق Github:

 import { createAppAuth } from "@octokit/auth-app" ;
const octokit = new Octokit ( {
  authStrategy : createAppAuth ,
  auth : {
    appId : 1 ,
    privateKey : "-----BEGIN PRIVATE KEY-----n..." ,
    installationId : 123 ,
  } ,
} ) ;

// authenticates as app based on request URLs
const {
  data : { slug } ,
} = await octokit . rest . apps . getAuthenticated ( ) ;

// creates an installation access token as needed
// assumes that installationId 123 belongs to @octocat, otherwise the request will fail
await octokit . rest . issues . create ( {
  owner : "octocat" ,
  repo : "hello-world" ,
  title : "Hello world from " + slug ,
} ) ;

يمكنك استخدام App أو OAuthApp SDKs التي توفر واجهات برمجة التطبيقات والأسلاك الداخلية لتغطية معظم حالات الاستخدام.

على سبيل المثال ، لتنفيذ ما سبق باستخدام App

 const app = new App ( { appId , privateKey } ) ;
const { data : slug } = await app . octokit . rest . apps . getAuthenticated ( ) ;
const octokit = await app . getInstallationOctokit ( 123 ) ;
await octokit . rest . issues . create ( {
  owner : "octocat" ,
  repo : "hello-world" ,
  title : "Hello world from " + slug ,
} ) ;

تعرف على المزيد حول كيفية عمل استراتيجيات المصادقة أو كيفية إنشاء خاص بك.

خوادم الوكيل (node.js فقط)

بشكل افتراضي ، لا يستخدم عميل Octokit API متغيرات بيئة خادم الوكيل القياسية. لإضافة دعم لخوادم الوكيل ، ستحتاج إلى توفير عميل HTTPS يدعمها مثل undici.ProxyAgent() .

على سبيل المثال ، من شأنه أن يستخدم ProxyAgent لتقديم الطلبات من خلال خادم وكيل:

 import { fetch as undiciFetch , ProxyAgent } from 'undici' ;

const myFetch = ( url , options ) => {
  return undiciFetch ( url , {
    ... options ,
    dispatcher : new ProxyAgent ( < your_proxy_url > )
  } )
}

const octokit = new Octokit ( {
  request : {
     fetch : myFetch
  } ,
} ) ;

إذا كنت تكتب وحدة تستخدم Octokit وتم تصميمها لاستخدامها من قبل أشخاص آخرين ، فيجب عليك التأكد من أن المستهلكين يمكنهم توفير وكيل بديل Octokit أو كمعلمة لمكالمات محددة مثل:

 import { fetch as undiciFetch , ProxyAgent } from 'undici' ;

const myFetch = ( url , options ) => {
  return undiciFetch ( url , {
    ... options ,
    dispatcher : new ProxyAgent ( < your_proxy_url > )
  } )
}

octokit . rest . repos . get ( {
  owner ,
  repo ,
  request : {
    fetch : myFetch
  } ,
} ) ; 

جلب مفقود

إذا حصلت على الخطأ التالي:

لم يتم تعيين الجلب. يرجى تمرير تطبيق الجلب كأوكوكيت جديد ({request: {fetch}}).

ربما يعني ذلك أنك تحاول تشغيل Octokit مع إصدار غير مدعوم من NodeJS. يتطلب Octokit العقدة 18 أو أعلى ، والتي تشمل واجهة برمجة تطبيقات Fetch الأصلية.

لتجاوز هذه المشكلة ، يمكنك توفير تطبيق fetch الخاص بك (أو إصدار مدمج مثل node-fetch ) مثل هذا:

 import fetch from "node-fetch" ;

const octokit = new Octokit ( {
  request : {
    fetch : fetch ,
  } ,
} ) ;

استراحة API

هناك طريقتان لاستخدام Github Rest API ، و octokit.rest.* أساليب نقطة النهاية و octokit.request . كلاهما يتصرف بنفس الطريقة ، تتم إضافة طرق octokit.rest.* فقط للراحة ، ويستخدمون octokit.request داخليًا.

على سبيل المثال

 await octokit . rest . issues . create ( {
  owner : "octocat" ,
  repo : "hello-world" ,
  title : "Hello, world!" ,
  body : "I created this issue using Octokit!" ,
} ) ;

هو نفسه

 await octokit . request ( "POST /repos/{owner}/{repo}/issues" , {
  owner : "octocat" ,
  repo : "hello-world" ,
  title : "Hello, world!" ,
  body : "I created this issue using Octokit!" ,
} ) ;

في كلتا الحالتين ، يتم مصادقة طلب معين ، وإعادة محاكاته ، وخنقه بشفافية بواسطة مثيل octokit الذي يدير أيضًا رؤوس accept user-agent حسب الحاجة.

يمكن استخدام octokit.request لإرسال الطلبات إلى مجالات أخرى عن طريق تمرير عنوان URL الكامل وإرسال طلبات إلى نقاط النهاية التي لم يتم توثيقها (بعد) في وثائق API الخاصة بـ Github.

octokit.rest أساليب نقطة النهاية

كل نقطة نهاية Github REST API لها طريقة octokit.rest المرتبطة بتحسين قابلية قراءة التعليمات البرمجية وراحة المطور. انظر @octokit/plugin-rest-endpoint-methods للحصول على التفاصيل الكاملة.

مثال: إنشاء مشكلة

 await octokit . rest . issues . create ( {
  owner : "octocat" ,
  repo : "hello-world" ,
  title : "Hello, world!" ,
  body : "I created this issue using Octokit!" ,
} ) ;

يتم إنشاء طرق نقطة النهاية octokit.rest تلقائيًا من مواصفات OpenAPI الخاصة بـ Github. نحن نتتبع معرف التشغيل وتغييرات اسم المعلمة من أجل تنفيذ تحذيرات الإهمال وتقليل تواتر التغييرات.

تحت الأغطية ، كل طريقة نقطة النهاية هي مجرد octokit.request مع مجموعة الافتراضات ، لذلك فهي تدعم نفس المعلمات وكذلك .endpoint() API.

octokit.request()

يمكنك استدعاء واجهة برمجة تطبيقات GitHub Rest مباشرة باستخدام octokit.request . تتطابق API request لتطابق وثائق API الخاصة بـ GitHub 1: 1 ، لذا فإن أي شيء تراه هناك ، يمكنك الاتصال باستخدام request . انظر @octokit/request لجميع التفاصيل.

مثال: إنشاء مشكلة

يبدو أن استدعاء octokit.request API المقابل لوثائق إنشاء القضية مثل هذا:

 // https://docs.github.com/en/rest/reference/issues#create-an-issue
await octokit . request ( "POST /repos/{owner}/{repo}/issues" , {
  owner : "octocat" ,
  repo : "hello-world" ,
  title : "Hello, world!" ,
  body : "I created this issue using Octokit!" ,
} ) ;

الوسيطة الأولى هي مسار API REST كما هو مدرج في وثائق واجهة برمجة تطبيقات Github. الوسيطة الثانية هي كائن له جميع المعلمات ، بغض النظر عما إذا كانت تستخدم في المسار أو الاستعلام أو الجسم.

ترقيم الصفحات

جميع نقاط نهاية API REST التي ترجع تراجع العناصر الثلاثين الأولى بشكل افتراضي. إذا كنت ترغب في استرداد جميع العناصر ، فيمكنك استخدام واجهة برمجة تطبيقات ترقيم الصفحات. تتوقع واجهة برمجة تطبيقات ترقيم الصفحات مسار REST API كوسيطة أولى ، ولكن يمكنك أيضًا تمرير أي من octokit.rest.*.list* أساليب للراحة وقابلية قراءة الكود الأفضل.

مثال: تكرار من خلال جميع القضايا في مستودع

 const iterator = octokit . paginate . iterator ( octokit . rest . issues . listForRepo , {
  owner : "octocat" ,
  repo : "hello-world" ,
  per_page : 100 ,
} ) ;

// iterate through each response
for await ( const { data : issues } of iterator ) {
  for ( const issue of issues ) {
    console . log ( "Issue #%d: %s" , issue . number , issue . title ) ;
  }
}

يعد استخدام Iterator Async هو الطريقة الأكثر فعالية للذاكرة للتكرار من خلال جميع العناصر. ولكن يمكنك أيضًا استرداد جميع العناصر في مكالمة واحدة

 const issues = await octokit . paginate ( octokit . rest . issues . listForRepo , {
  owner : "octocat" ,
  repo : "hello-world" ,
  per_page : 100 ,
} ) ; 

تنسيقات نوع الوسائط

يمكن تعيين تنسيقات نوع الوسائط باستخدام mediaType: { format } في كل طلب.

مثال: استرداد المحتوى الخام لملف package.json

 const { data } = await octokit . rest . repos . getContent ( {
  mediaType : {
    format : "raw" ,
  } ,
  owner : "octocat" ,
  repo : "hello-world" ,
  path : "package.json" ,
} ) ;
console . log ( "package name: %s" , JSON . parse ( data ) . name ) ;

تعرف على المزيد حول تنسيقات نوع الوسائط.

طلب معالجة الخطأ

الوحدة النمطية المستقلة: @octokit/request-error

لمعالجة خطأ الطلب ، استيراد RequestError واستخدم try...catch President.

 import { RequestError } from "octokit" ; 

 try {
  // your code here that sends at least one Octokit request
  await octokit . request ( "GET /" ) ;
} catch ( error ) {
  // Octokit errors are instances of RequestError, so they always have an `error.status` property containing the HTTP response code.
  if ( error instanceof RequestError ) {
    // handle Octokit error
    // error.message; // Oops
    // error.status; // 500
    // error.request; // { method, url, headers, body }
    // error.response; // { url, status, headers, data }
  } else {
    // handle all other errors
    throw error ;
  }
}

استعلامات API GraphQL

يدعم Octokit أيضًا واجهة برمجة تطبيقات Github's GraphQL مباشرة - يمكنك استخدام نفس الاستعلامات الموضحة في الوثائق ومتاحة في مستكشف GraphQL في مكالماتك باستخدام octokit.graphql .

مثال: احصل على تسجيل الدخول للمستخدم المصادق عليه

 const {
  viewer : { login } ,
} = await octokit . graphql ( `{
  viewer {
    login
  }
}` ) ;

يمكن تمرير المتغيرات كوسيطة ثانية

 const { lastIssues } = await octokit . graphql (
  `
    query lastIssues($owner: String!, $repo: String!, $num: Int = 3) {
      repository(owner: $owner, name: $repo) {
        issues(last: $num) {
          edges {
            node {
              title
            }
          }
        }
      }
    }
  ` ,
  {
    owner : "octokit" ,
    repo : "graphql.js" ,
  } ,
) ; 

ترقيم الصفحات

يقوم Github's GraphQL API بإرجاع 100 عنصر كحد أقصى. إذا كنت ترغب في استرداد جميع العناصر ، فيمكنك استخدام واجهة برمجة تطبيقات ترقيم الصفحات.

مثال: احصل على كل المشكلات

 const { allIssues } = await octokit . graphql . paginate (
  `
    query allIssues($owner: String!, $repo: String!, $num: Int = 10, $cursor: String) {
      repository(owner: $owner, name: $repo) {
        issues(first: $num, after: $cursor) {
          edges {
            node {
              title
            }
          }
          pageInfo {
            hasNextPage
            endCursor
          }
        }
      }
    }
  ` ,
  {
    owner : "octokit" ,
    repo : "graphql.js" ,
  } ,
) ;

تعرف على المزيد حول استخدام Github's GraphQL ترقيم ترقيم الصفحات.

معاينات المخطط

يمكن تمكين المعاينات باستخدام خيار {mediaType: previews: [] } .

مثال: إنشاء تسمية

 await octokit . graphql (
  `mutation createLabel($repositoryId:ID!,name:String!,color:String!) {
  createLabel(input:{repositoryId:$repositoryId,name:$name}) {
    label: {
      id
    }
  }
}` ,
  {
    repositoryId : 1 ,
    name : "important" ,
    color : "cc0000" ,
    mediaType : {
      previews : [ "bane" ] ,
    } ,
  } ,
) ;

تعرف على المزيد حول معاينات مخطط Github GraphQL

عميل التطبيق

يجمع عميل App بين ميزات تطبيقات GitHub و Webhooks و Oauth

تطبيق جيثب

الوحدة المستقلة : @octokit/app

بالنسبة للتكامل ، تعد تطبيقات GitHub وسيلة للمصادقة والترخيص. يمكن تسجيل تطبيق GitHub على حساب مستخدم أو مؤسسة GitHub. يحدد تسجيل تطبيق GitHub مجموعة من الأذونات وأحداث Webhooks التي يريد تلقيها وتقدم مجموعة من أوراق الاعتماد في المقابل. يمكن للمستخدمين منح الوصول إلى المستودعات عن طريق تثبيتها.

تتطلب بعض نقاط نهاية API من تطبيق GitHub المصادقة بنفسه باستخدام رمز الويب JSON (JWT). للطلبات التي تؤثر على التثبيت ، يجب إنشاء رمز الوصول إلى التثبيت باستخدام بيانات اعتماد التطبيق ومعرف التثبيت.

يعتني عميل App بكل ذلك لك.

مثال: إرسال حدث مستودع في كل مستودع يتم تثبيت التطبيق على

 import { App } from "octokit" ;

const app = new App ( { appId , privateKey } ) ;

for await ( const { octokit , repository } of app . eachRepository . iterator ( ) ) {
  // https://docs.github.com/en/rest/reference/repos#create-a-repository-dispatch-event
  await octokit . rest . repos . createDispatchEvent ( {
    owner : repository . owner . login ,
    repo : repository . name ,
    event_type : "my_event" ,
    client_payload : {
      foo : "bar" ,
    } ,
  } ) ;
  console . log ( "Event dispatched for %s" , repository . full_name ) ;
}

مثال: الحصول على مثيل octokit مصادق عليه كتثبيت

 const octokit = await app . getInstallationOctokit ( 123 ) ;

تعرف على المزيد حول التطبيقات.

Webhooks

الوحدة المستقلة : @octokit/webhooks

عند تثبيت تطبيق ، سيتم إرسال الأحداث التي يتم إرسال طلبات تسجيل التطبيق كطلبات إلى عنوان URL لـ WebHook في تسجيل التطبيق.

يتم توقيع طلبات أحداث WebHook باستخدام WebHook Secret ، والتي تعد أيضًا جزءًا من تسجيل التطبيق. يجب التحقق من هذا السر قبل التعامل مع حمولة الطلب.

توفر app.webhooks.*

مثال: إنشاء تعليق على قضايا جديدة

 import { createServer } from "node:http" ;
import { App , createNodeMiddleware } from "octokit" ;

const app = new App ( {
  appId ,
  privateKey ,
  webhooks : { secret } ,
} ) ;

app . webhooks . on ( "issues.opened" , ( { octokit , payload } ) => {
  return octokit . rest . issues . createComment ( {
    owner : payload . repository . owner . login ,
    repo : payload . repository . name ,
    issue_number : payload . issue . number ,
    body : "Hello, World!" ,
  } ) ;
} ) ;

// Your app can now receive webhook events at `/api/github/webhooks`
createServer ( createNodeMiddleware ( app ) ) . listen ( 3000 ) ;

بالنسبة للبيئات بدون خادم ، يمكنك التحقق بشكل صريح وتلقي حدث

 await app . webhooks . verifyAndReceive ( {
  id : request . headers [ "x-github-delivery" ] ,
  name : request . headers [ "x-github-event" ] ,
  signature : request . headers [ "x-hub-signature-256" ] ,
  payload : request . body ,
} ) ;

تعرف على المزيد حول github webhooks.

Oauth

الوحدة المستقلة: @octokit/oauth-app

تدعم كل من تطبيقات OAUTH وتطبيقات GitHub مصادقة مستخدمي GitHub باستخدام OAUTH ، راجع تفويض تطبيقات OAUTH وتحديد وتصريح المستخدمين بتطبيقات GitHub.

هناك بعض الاختلافات:

• فقط تطبيقات OAuth تدعم النطاقات. تحتوي تطبيقات GitHub على أذونات ، ويتم منح الوصول عبر تثبيتات التطبيق على المستودعات.
• تدعم تطبيقات GitHub فقط رموز المستخدم الصالحة الصلاحية
• تدعم تطبيقات GitHub فقط إنشاء رمز مميز لتقليل الأذونات والوصول إلى المستودع

App هو لتطبيقات github. إذا كنت بحاجة إلى وظيفة خاصة بتطبيق OAUTH ، فاستخدم OAuthApp بدلاً من ذلك.

مثال: شاهد مستودعًا عندما يقوم المستخدم بتسجيل الدخول باستخدام تدفق الويب OAUTH

 import { createServer } from "node:http" ;
import { App , createNodeMiddleware } from "octokit" ;

const app = new App ( {
  oauth : { clientId , clientSecret } ,
} ) ;

app . oauth . on ( "token.created" , async ( { token , octokit } ) => {
  await octokit . rest . activity . setRepoSubscription ( {
    owner : "octocat" ,
    repo : "hello-world" ,
    subscribed : true ,
  } ) ;
} ) ;

// Your app can receive the OAuth redirect at /api/github/oauth/callback
// Users can initiate the OAuth web flow by opening /api/github/oauth/login
createServer ( createNodeMiddleware ( app ) ) . listen ( 3000 ) ;

بالنسبة للبيئات غير الخاطئة ، يمكنك تبادل code بشكل صريح من إعادة توجيه تدفق الويب OAUTH للحصول على رمز الوصول. app.oauth.createToken() إرجاع كائن مصادقة وينطلق حدث "token.created".

 const { token } = await app . oauth . createToken ( {
  code : request . query . code ,
} ) ;

مثال: إنشاء رمز رمز باستخدام تدفق الجهاز.

 const { token } = await app . oauth . createToken ( {
  async onVerification ( verification ) {
    await sendMessageToUser (
      request . body . phoneNumber ,
      `Your code is ${ verification . user_code } . Enter it at ${ verification . verification_uri } ` ,
    ) ;
  } ,
} ) ;

مثال: إنشاء خادم تطبيق OAUTH مع نطاقات افتراضية

 import { createServer } from "node:http" ;
import { OAuthApp , createNodeMiddleware } from "octokit" ;

const app = new OAuthApp ( {
  clientId ,
  clientSecret ,
  defaultScopes : [ "repo" , "gist" ] ,
} ) ;

app . oauth . on ( "token" , async ( { token , octokit } ) => {
  await octokit . rest . gists . create ( {
    description : "I created this gist using Octokit!" ,
    public : true ,
    files : {
      "example.js" : `/* some code here */` ,
    } ,
  } ) ;
} ) ;

// Your app can receive the OAuth redirect at /api/github/oauth/callback
// Users can initiate the OAuth web flow by opening /api/oauth/login
createServer ( createNodeMiddleware ( app ) ) . listen ( 3000 ) ;

خادم التطبيق

بعد تسجيل تطبيق GitHub الخاص بك ، تحتاج إلى إنشاء خادم ونشره يمكنه استرداد طلبات حدث WebHook من GitHub وكذلك قبول عمليات إعادة التوجيه من تدفق الويب لمستخدم OAUTH.

إن أبسط طريقة لإنشاء مثل هذا الخادم هي استخدام createNodeMiddleware() ، فهي تعمل مع كل من Node's http.createServer() بالإضافة إلى برامج وسيطة صريحة.

الطرق الافتراضية التي تكشفها البرامج الوسيطة

طريق	وصف الطريق
POST /api/github/webhooks	نقطة النهاية لتلقي طلبات حدث Github Webhook
GET /api/github/oauth/login	إعادة توجيه إلى نقطة نهاية ترخيص جيثب. يقبل اختياري ?state و ?scopes المعلمات الاستعلام. ?scopes هي قائمة مفصولة بفاصلة بأسماء نطاق OAUTH المدعومة
GET /api/github/oauth/callback	نقطة النهاية لإعادة توجيه العميل. هذا هو المكان الذي يتم فيه تشغيل الحدث token
POST /api/github/oauth/token	تبادل رمز التفويض لرمز الوصول إلى OAuth. إذا نجحت ، يتم تشغيل الحدث token .
GET /api/github/oauth/token	تحقق مما إذا كان الرمز مميزًا صالحًا. يجب المصادقة باستخدام الرمز المميز في رأس Authorization . يستخدم POST /applications/{client_id}/token point
PATCH /api/github/oauth/token	إعادة تعيين رمز رمزي (يبطل واحد الحالي ، وإرجاع رمز جديد). يجب المصادقة باستخدام الرمز المميز في رأس Authorization . يستخدم PATCH /applications/{client_id}/token نقطة نهاية.
PATCH /api/github/oauth/refresh-token	يقوم بتحديث رمز منتهية الصلاحية (يبطل واحد الحالي ، وإرجاع الرمز المميز الجديد للوصول وإعادة تحديث الرمز المميز). يجب المصادقة باستخدام الرمز المميز في رأس Authorization . يستخدم Github POST https://github.com/login/oauth/access_token Oauth Endpoint.
POST /api/github/oauth/token/scoped	ينشئ رمزًا محددًا (لا يبطئ الرمز الحالي). يجب المصادقة باستخدام الرمز المميز في رأس Authorization . يستخدم GitHub POST /applications/{client_id}/token/scoped endpoint.
DELETE /api/github/oauth/token	يبطل الرمز المميز الحالي ، في الأساس ما يعادل تسجيل الخروج. يجب المصادقة باستخدام الرمز المميز في رأس Authorization .
DELETE /api/github/oauth/grant	يلغي منحة المستخدم ، في الأساس ما يعادل إلغاء التثبيت. يجب المصادقة باستخدام الرمز المميز في رأس Authorization .

مثال: إنشاء خادم github مع Express

 import express from "express" ;
import { App , createNodeMiddleware } from "octokit" ;

const expressApp = express ( ) ;
const octokitApp = new App ( {
  appId ,
  privateKey ,
  webhooks : { secret } ,
  oauth : { clientId , clientSecret } ,
} ) ;

expressApp . use ( createNodeMiddleware ( app ) ) ;

expressApp . listen ( 3000 , ( ) => {
  console . log ( `Example app listening at http://localhost:3000` ) ;
} ) ;

OAUTH لتطبيقات المتصفح

يجب ألا تعرض سر عميل تطبيقك للمستخدم ، لذلك لا يمكنك استخدام مُنشئ App . بدلاً من ذلك ، يتعين عليك إنشاء خادم باستخدام مُنشئ App الذي يعرض طرق /api/github/oauth/* ، والتي من خلالها يمكنك من خلالها تنفيذ تسجيل الدخول إلى OAUTH للتطبيقات التي تعمل في متصفح الويب.

إذا قمت بتعيين (User) Authorization callback URL على تطبيق state الخاص app.oauthLoginUrl() ، فأنت بحاجة إلى قراءة code ?code=...&state=...

إذا قمت بتشغيل خادم تطبيق كما هو موضح أعلاه ، فإن المسار الافتراضي للقيام بذلك هو POST /api/github/oauth/token .

بمجرد استرداد الرمز المميز بنجاح ، يوصى أيضًا بإزالة ?code=...&state=...

 const code = new URL ( location . href ) . searchParams . get ( "code" ) ;
if ( code ) {
  // remove ?code=... from URL
  const path =
    location . pathname +
    location . search . replace ( / b(code|state)=w+ / g , "" ) . replace ( / [?&]+$ / , "" ) ;
  history . replaceState ( { } , "" , path ) ;

  // exchange the code for a token with your backend.
  // If you use https://github.com/octokit/oauth-app.js
  // the exchange would look something like this
  const response = await fetch ( "/api/github/oauth/token" , {
    method : "POST" ,
    headers : {
      "content-type" : "application/json" ,
    } ,
    body : JSON . stringify ( { code } ) ,
  } ) ;
  const { token } = await response . json ( ) ;
  // `token` is the OAuth Access Token that can be use

  const { Octokit } = await import ( "https://esm.sh/@octokit/core" ) ;
  const octokit = new Octokit ( { auth : token } ) ;

  const {
    data : { login } ,
  } = await octokit . request ( "GET /user" ) ;
  alert ( "Hi there, " + login ) ;
}

؟ نحن نعمل على @octokit/auth-oauth-user-client لتوفير واجهة برمجة تطبيقات بسيطة لجميع الطرق المتعلقة برموز مستخدم Oauth.

تتمثل الخطة في إضافة مسار GET /api/github/oauth/octokit.js الجديد إلى البرامج الوسيطة العقدة التي ستعيد ملف JavaScript الذي يمكن استيراده إلى ملف HTML. سيجعل مثيل octokit مسبقًا متاحًا.

عميل الإجراء

الوحدة المستقلة: @octokit/action

؟ عميل Action نجا بالكامل معلق. يمكنك استخدام @actions/github في الوقت الحالي

رخصة

معهد ماساتشوستس للتكنولوجيا