twilio ruby

تويليو روبي

التوثيق

يمكن العثور على وثائق Twilio API هنا.

الإصدارات الفردية هنا.

الإصدارات

يستخدم twilio-ruby نسخة معدلة من الإصدار الدلالي لجميع التغييرات. راجع هذه الوثيقة للحصول على التفاصيل.

إصدارات روبي المدعومة

تدعم هذه المكتبة تطبيقات روبي التالية:

• روبي 2.4

• روبي 2.5

• روبي 2.6

• روبي 2.7

• روبي 3.0

• روبي 3.1

• روبي 3.2

• جي روبي 9.2

• جي روبي 9.3

• جي روبي 9.4

الترحيل من 5.x

دليل الترقية

تثبيت

للتثبيت باستخدام Bundler، احصل على أحدث إصدار ثابت:

 gem 'twilio-ruby' , '~> 7.3.6'

لتثبيت twilio-ruby يدويًا عبر Rubygems، قم ببساطة بتثبيت الجوهرة:

gem install twilio-ruby -v 7.3.6

لبناء فرع التطوير وتثبيته بنفسك من أحدث مصدر:

git clone [email protected]:twilio/twilio-ruby.git
cd twilio-ruby
make install

معلومات إذا كان سطر الأوامر يعطيك رسالة خطأ تفيد برفض الإذن، فحاول تشغيل الأوامر المذكورة أعلاه باستخدام sudo.

على سبيل المثال: sudo gem install twilio-ruby

اختبار التثبيت الخاص بك

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

 require "twilio-ruby"

# Your Account SID and Auth Token from console.twilio.com
account_sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
auth_token = "your_auth_token"

@client = Twilio :: REST :: Client . new account_sid , auth_token
message = @client . messages . create (
  body : "Hello from Ruby" ,
  to : "[phone]" ,  # Text this number
  from : "[phone]" , # From a valid Twilio number
)

puts message . sid

تحذير: لا بأس في ترميز بيانات الاعتماد الخاصة بك عند الاختبار محليًا، ولكن يجب عليك استخدام متغيرات البيئة للحفاظ على سريتها قبل الالتزام بأي تعليمات برمجية أو نشرها في الإنتاج. راجع كيفية تعيين متغيرات البيئة لمزيد من المعلومات.

الاستخدام

مصادقة العميل

 require 'twilio-ruby'

# Your Account SID and Auth Token from console.twilio.com
account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'

# Initialize the Twilio Client with your credentials
@client = Twilio :: REST :: Client . new account_sid , auth_token

استخدم مفتاح API

 require 'twilio-ruby'

# Your Account SID from console.twilio.com
account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
# API Key from twilio.com/console/project/api-keys
api_key_sid = 'zzzzzzzzzzzzzzzzzzzzzz'
api_key_secret = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'

# set up a client to talk to the Twilio REST API using an API Key
@client = Twilio :: REST :: Client . new api_key_sid , api_key_secret , account_sid

حدد المنطقة و/أو الحافة

للاستفادة من البنية التحتية العالمية لـ Twilio، حدد المنطقة المستهدفة و/أو الحافة للعميل:

 # set up a client to talk to the Twilio REST API over a specific region and edge
@client = Twilio :: REST :: Client . new account_sid , auth_token , nil , 'au1'
@client . edge = 'sydney'

# you may also specify the region and/or edge after client creation
@client = Twilio :: REST :: Client . new account_sid , auth_token
@client . region = 'au1'
@client . edge = 'sydney'

سيؤدي هذا إلى تحويل hostname من api.twilio.com إلى api.sydney.au1.twilio.com .

إجراء مكالمة

 @client . calls . create (
  from : '[phone]' ,
  to : '[phone]' ,
  url : 'http://example.com'
)

أرسل رسالة نصية قصيرة

 @client . messages . create (
  from : '[phone]' ,
  to : '[phone]' ,
  body : 'Hey there!'
)

قائمة رسائل SMS الخاصة بك

 @client . messages . list ( limit : 20 )

جلب رسالة SMS واحدة عن طريق Sid

 # put the message sid you want to retrieve here:
message_sid = 'SMxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
@client . messages ( message_sid ) . fetch

التكرار من خلال السجلات

تقوم المكتبة تلقائيًا بمعالجة الترحيل نيابةً عنك. تحتوي المجموعات، مثل calls messages ، على طرق list ودفق لتلك الصفحة أسفل الغطاء. باستخدام كل من list stream ، يمكنك تحديد عدد السجلات التي تريد تلقيها ( limit ) والحد الأقصى للحجم الذي تريد جلبه لكل صفحة ( page_size ). ستقوم المكتبة بعد ذلك بالتعامل مع المهمة نيابةً عنك.

تقوم list بجلب جميع السجلات بفارغ الصبر وتعيدها كقائمة، بينما يقوم stream بإرجاع العداد ويسترد بتكاسل صفحات السجلات أثناء التكرار على المجموعة. يمكنك أيضًا الصفحة يدويًا باستخدام طريقة page .

لمزيد من المعلومات حول هذه الطرق، قم بعرض مستندات المكتبة التي تم إنشاؤها تلقائيًا.

 require 'twilio-ruby'

account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

@client = Twilio :: REST :: Client . new ( account_sid , auth_token )

@client . calls . list
       . each do | call |
         puts call . direction
       end

تمكين تسجيل التصحيح

لتمكين تسجيل التصحيح، قم بتمرير مثيل "المسجل" إلى العميل مع تعيين المستوى على "DEBUG" على الأقل

 @client = Twilio :: REST :: Client . new account_sid , auth_token
myLogger = Logger . new ( STDOUT )
myLogger . level = Logger :: DEBUG
@client . logger = myLogger

@client = Twilio :: REST :: Client . new account_sid , auth_token
myLogger = Logger . new ( 'my_log.log' )
myLogger . level = Logger :: DEBUG
@client . logger = myLogger

التعامل مع الاستثناءات {#exceptions}

إذا قامت Twilio API بإرجاع استجابة HTTP بمستوى 400 أو 500، فستقوم مكتبة twilio-ruby بطرح Twilio::REST::RestError . تعد الأخطاء على مستوى 400 أمرًا طبيعيًا أثناء تشغيل واجهة برمجة التطبيقات ( “Invalid number” ، “Cannot deliver SMS to that number” ، على سبيل المثال) ويجب التعامل معها بشكل مناسب.

 require 'twilio-ruby'

account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

@client = Twilio :: REST :: Client . new account_sid , auth_token

begin
  messages = @client . messages . list ( limit : 20 )
rescue Twilio :: REST :: RestError => e
  puts e . message
end

تصحيح طلبات API

للمساعدة في تصحيح الأخطاء، تسمح لك المكتبة بالوصول إلى كائنات الطلب والاستجابة الأساسية. تم تضمين هذه الإمكانية في عميل HTTP الافتراضي الذي يأتي مع المكتبة.

على سبيل المثال، يمكنك استرداد رمز الحالة للاستجابة الأخيرة كما يلي:

 require 'rubygems' # Not necessary with ruby 1.9 but included for completeness
require 'twilio-ruby'

# Your Account SID and Auth Token from console.twilio.com
account_sid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'
auth_token = 'your_auth_token'

@client = Twilio :: REST :: Client . new ( account_sid , auth_token )

@message = @client . messages . create (
  to : '[phone]' ,
  from : '[phone]' ,
  body : 'Ahoy!'
)

# Retrieve the status code of the last response from the HTTP client
puts @client . http_client . last_response . status_code

تخصيص عميل HTTP الخاص بك

يستخدم twilio-ruby Faraday لتقديم طلبات HTTP. يمكنك إخبار Twilio::REST::Client باستخدام أي من محولات Faraday كما يلي:

 @client . http_client . adapter = :typhoeus

لاستخدام عميل HTTP مخصص مع مكتبة المساعد هذه، يرجى الاطلاع على المثال المتقدم لكيفية القيام بذلك.

لتطبيق التخصيصات مثل البرامج الوسيطة، يمكنك استخدام التابع configure_connection كما يلي:

 @client . http_client . configure_connection do | faraday |
  faraday . use SomeMiddleware
end

ابدأ باستخدام رموز قدرة العميل

إذا كنت بحاجة فقط إلى إنشاء رمز القدرة لاستخدامه مع Twilio Client، فيمكنك القيام بذلك:

 require 'twilio-ruby'

# put your own account credentials here:
account_sid = 'ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
auth_token = 'yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'

# set up
capability = Twilio :: JWT :: ClientCapability . new account_sid , auth_token

# allow outgoing calls to an application
outgoing_scope = Twilio :: JWT :: ClientCapability :: OutgoingClientScope . new 'AP11111111111111111111111111111111'
capability . add_scope ( outgoing_scope )

# allow incoming calls to 'andrew'
incoming_scope = Twilio :: JWT :: ClientCapability :: IncomingClientScope . new 'andrew'
capability . add_scope ( incoming_scope )

# generate the token string
@token = capability . to_s

يوجد مستند أكثر تفصيلاً قليلاً في قسم القدرة في الويكي.

إنشاء TwiML

للتحكم في المكالمات الهاتفية، يحتاج تطبيقك إلى إخراج TwiML.

يمكنك إنشاء استجابة TwiML مثل هذا:

 require 'twilio-ruby'

response = Twilio :: TwiML :: VoiceResponse . new do | r |
  r . say ( message : 'hello there' , voice : 'alice' )
  r . dial ( caller_id : '[phone]' ) do | d |
    d . client 'jenny'
  end
end

# print the result
puts response . to_s

سيؤدي هذا إلى طباعة ما يلي (باستثناء المسافة البيضاء):

xml version = " 1.0 " encoding = " UTF-8 " ?>
< Response >
  < Say voice = " alice " >hello thereSay >
  < Dial callerId = " [phone] " >
    < Client >jennyClient >
  Dial >
Response >

صورة عامل الميناء

يتم استخدام Dockerfile الموجود في هذا المستودع وصورة twilio/twilio-ruby Docker الخاصة به حاليًا بواسطة Twilio لأغراض الاختبار فقط.

الحصول على المساعدة

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

إذا وجدت بدلاً من ذلك خطأً في المكتبة أو كنت ترغب في إضافة ميزات جديدة، فاستمر وافتح المشكلات أو اسحب الطلبات مقابل هذا الريبو!