সোলার API ওয়েব পরিষেবাগুলি ব্যবহার করে সর্বোত্তম অনুশীলন

Google মানচিত্র প্ল্যাটফর্ম ওয়েব পরিষেবাগুলি হল আপনার মানচিত্র অ্যাপ্লিকেশনগুলির জন্য ভৌগলিক ডেটা প্রদান করে Google পরিষেবাগুলিতে HTTP ইন্টারফেসের একটি সংগ্রহ৷

এই নির্দেশিকাটি আপনার ওয়েব পরিষেবার অনুরোধগুলি সেট আপ করতে এবং পরিষেবা প্রতিক্রিয়া প্রক্রিয়াকরণের জন্য দরকারী কিছু সাধারণ অনুশীলন বর্ণনা করে৷ Solar API-এর সম্পূর্ণ ডকুমেন্টেশনের জন্য বিকাশকারীর নির্দেশিকা পড়ুন।

একটি ওয়েব সেবা কি?

Google মানচিত্র প্ল্যাটফর্ম ওয়েব পরিষেবাগুলি বহিরাগত পরিষেবাগুলি থেকে মানচিত্র API ডেটা অনুরোধ করার এবং আপনার মানচিত্র অ্যাপ্লিকেশনগুলির মধ্যে ডেটা ব্যবহার করার জন্য একটি ইন্টারফেস৷ Google মানচিত্র প্ল্যাটফর্ম পরিষেবার শর্তাবলীতে লাইসেন্স সীমাবদ্ধতা অনুসারে এই পরিষেবাগুলি একটি মানচিত্রের সাথে ব্যবহার করার জন্য ডিজাইন করা হয়েছে৷

মানচিত্র API-এর ওয়েব পরিষেবাগুলি পরিষেবাগুলির আর্গুমেন্ট হিসাবে নির্দিষ্ট URLগুলিতে HTTP(S) অনুরোধগুলি ব্যবহার করে, URL প্যারামিটার এবং/অথবা JSON- ফর্ম্যাট পোস্ট ডেটা ব্যবহার করে৷ সাধারণত, এই পরিষেবাগুলি আপনার অ্যাপ্লিকেশন দ্বারা পার্সিং এবং/অথবা প্রক্রিয়াকরণের জন্য JSON হিসাবে প্রতিক্রিয়া বডিতে ডেটা ফেরত দেয়।

নিম্নলিখিত উদাহরণটি dataLayers পদ্ধতিতে একটি REST GET অনুরোধের URL দেখায়:

https://solar.googleapis.com/v1/dataLayers:get?parameters

দ্রষ্টব্য : সমস্ত Solar API অ্যাপ্লিকেশনের প্রমাণীকরণ প্রয়োজন। প্রমাণীকরণ শংসাপত্র সম্পর্কে আরও তথ্য পান।

SSL/TLS অ্যাক্সেস

API কী ব্যবহার করে বা ব্যবহারকারীর ডেটা ধারণ করে এমন সমস্ত Google মানচিত্র প্ল্যাটফর্মের অনুরোধের জন্য HTTPS প্রয়োজন। সংবেদনশীল ডেটা ধারণ করে HTTP-এর মাধ্যমে করা অনুরোধ প্রত্যাখ্যান করা হতে পারে।

একটি বৈধ URL তৈরি করা

আপনি মনে করতে পারেন যে একটি "বৈধ" URL স্ব-প্রকাশ্য, কিন্তু এটি পুরোপুরি ক্ষেত্রে নয়। একটি ব্রাউজারে একটি ঠিকানা বারের মধ্যে প্রবেশ করা একটি URL, উদাহরণস্বরূপ, বিশেষ অক্ষর থাকতে পারে (যেমন "上海+中國" ); ট্রান্সমিশনের আগে ব্রাউজারটিকে সেই অক্ষরগুলিকে একটি ভিন্ন এনকোডিংয়ে অভ্যন্তরীণভাবে অনুবাদ করতে হবে। একই টোকেন দ্বারা, যেকোন কোড যা UTF-8 ইনপুট তৈরি করে বা গ্রহণ করে তা UTF-8 অক্ষর যুক্ত URL গুলিকে "বৈধ" হিসাবে বিবেচনা করতে পারে, তবে একটি ওয়েব সার্ভারে পাঠানোর আগে সেই অক্ষরগুলিকে অনুবাদ করতে হবে৷ এই প্রক্রিয়াটিকে URL-এনকোডিং বা শতাংশ-এনকোডিং বলা হয়।

বিশেষ চরিত্র

আমাদের বিশেষ অক্ষর অনুবাদ করতে হবে কারণ সমস্ত ইউআরএলকে ইউনিফর্ম রিসোর্স আইডেন্টিফায়ার (ইউআরআই) স্পেসিফিকেশন দ্বারা নির্দিষ্ট সিনট্যাক্সের সাথে সামঞ্জস্য করতে হবে। বাস্তবে, এর মানে হল যে ইউআরএলগুলিতে ASCII অক্ষরের একটি বিশেষ উপসেট থাকতে হবে: পরিচিত বর্ণসংখ্যার চিহ্ন এবং ইউআরএল-এর মধ্যে নিয়ন্ত্রণ অক্ষর হিসাবে ব্যবহারের জন্য কিছু সংরক্ষিত অক্ষর। এই টেবিলটি এই অক্ষরগুলিকে সংক্ষিপ্ত করে:

বৈধ URL অক্ষরের সারাংশ
সেট অক্ষর ইউআরএল ব্যবহার
আলফানিউমেরিক abcdefghijklm nopqrstuvwxyz ABCDEFGHIJKLM NOPQRSTUVWXYZ 0 1 2 3 4 5 6 7 8 9 টেক্সট স্ট্রিং, স্কিম ব্যবহার ( http ), পোর্ট ( 8080 ), ইত্যাদি।
অসংরক্ষিত - _ ~ টেক্সট স্ট্রিং
সংরক্ষিত ! *' (); : @ & = + $ , / ? % # [ ] অক্ষর এবং/অথবা টেক্সট স্ট্রিং নিয়ন্ত্রণ করুন

একটি বৈধ URL তৈরি করার সময়, আপনাকে অবশ্যই নিশ্চিত করতে হবে যে এতে কেবলমাত্র টেবিলে দেখানো অক্ষরগুলি রয়েছে৷ অক্ষরের এই সেটটি ব্যবহার করার জন্য একটি ইউআরএল কনফর্ম করলে সাধারণত দুটি সমস্যা দেখা দেয়, একটি বাদ দেওয়া এবং একটি প্রতিস্থাপন:

  • আপনি যে অক্ষরগুলি পরিচালনা করতে চান সেগুলি উপরের সেটের বাইরে বিদ্যমান। উদাহরণস্বরূপ,上海+中國-এর মতো বিদেশী ভাষার অক্ষরগুলিকে উপরের অক্ষরগুলি ব্যবহার করে এনকোড করা প্রয়োজন৷ জনপ্রিয় নিয়ম অনুসারে, স্পেসগুলি (যা ইউআরএল-এর মধ্যে অনুমোদিত নয়) প্রায়শই প্লাস '+' অক্ষর ব্যবহার করে উপস্থাপন করা হয়।
  • সংরক্ষিত অক্ষর হিসাবে উপরের সেটের মধ্যে অক্ষর বিদ্যমান, কিন্তু আক্ষরিকভাবে ব্যবহার করা প্রয়োজন। উদাহরণস্বরূপ ? ক্যোয়ারী স্ট্রিং এর শুরু নির্দেশ করতে URL-এর মধ্যে ব্যবহার করা হয়; আপনি যদি স্ট্রিং "? এবং The Mysterions" ব্যবহার করতে চান, তাহলে আপনাকে '?' এনকোড করতে হবে চরিত্র

ইউআরএল-এনকোড করা সমস্ত অক্ষর একটি '%' অক্ষর এবং তাদের UTF-8 অক্ষরের সাথে সম্পর্কিত একটি দুই-অক্ষরের হেক্স মান ব্যবহার করে এনকোড করা হয়েছে। উদাহরণস্বরূপ, UTF-8-এ上海+中國%E4%B8%8A%E6%B5%B7%2B%E4%B8%AD%E5%9C%8B হিসাবে URL-এনকোড করা হবে। স্ট্রিং ? and the Mysterians %3F+and+the+Mysterians বা %3F%20and%20the%20Mysterians হিসাবে ইউআরএল-এনকোড করা হবে।

এনকোডিং প্রয়োজন এমন সাধারণ অক্ষর

কিছু সাধারণ অক্ষর যা এনকোড করা আবশ্যক:

অনিরাপদ চরিত্র এনকোড করা মান
স্থান %20
" %22
< %3C
> %3E
# %23
% %25
| %7C

আপনি ব্যবহারকারীর ইনপুট থেকে প্রাপ্ত একটি URL রূপান্তর কখনও কখনও চতুর হয়. উদাহরণস্বরূপ, একজন ব্যবহারকারী "5ম এবং প্রধান সেন্ট" হিসাবে একটি ঠিকানা লিখতে পারেন। সাধারণত, আপনার ইউআরএল এর অংশগুলি থেকে তৈরি করা উচিত, যেকোনো ব্যবহারকারীর ইনপুটকে আক্ষরিক অক্ষর হিসাবে বিবেচনা করা উচিত।

উপরন্তু, সমস্ত Google মানচিত্র প্ল্যাটফর্ম ওয়েব পরিষেবা এবং স্ট্যাটিক ওয়েব API-এর জন্য URLগুলি 16384 অক্ষরের মধ্যে সীমাবদ্ধ৷ বেশিরভাগ পরিষেবার জন্য, এই অক্ষর সীমা খুব কমই ব্যবহার করা হবে। যাইহোক, মনে রাখবেন যে কিছু নির্দিষ্ট পরিষেবার বেশ কয়েকটি প্যারামিটার থাকে যার ফলে দীর্ঘ URL হতে পারে।

Google API-এর ভদ্র ব্যবহার

খারাপভাবে ডিজাইন করা এপিআই ক্লায়েন্টরা ইন্টারনেট এবং গুগল সার্ভার উভয়েই প্রয়োজনের চেয়ে বেশি লোড রাখতে পারে। এই বিভাগে API-এর ক্লায়েন্টদের জন্য কিছু সেরা অনুশীলন রয়েছে। এই সর্বোত্তম অনুশীলনগুলি অনুসরণ করা আপনাকে API গুলির অসাবধানতাবশত অপব্যবহারের জন্য আপনার অ্যাপ্লিকেশন ব্লক হওয়া এড়াতে সহায়তা করতে পারে।

সূচকীয় ব্যাকঅফ

বিরল ক্ষেত্রে আপনার অনুরোধ পরিবেশন করতে কিছু ভুল হতে পারে; আপনি একটি 4XX বা 5XX HTTP প্রতিক্রিয়া কোড পেতে পারেন, অথবা TCP সংযোগটি আপনার ক্লায়েন্ট এবং Google এর সার্ভারের মধ্যে কোথাও ব্যর্থ হতে পারে৷ প্রায়শই অনুরোধটি পুনরায় চেষ্টা করা সার্থক কারণ মূল ব্যর্থ হলে ফলোআপ অনুরোধ সফল হতে পারে। যাইহোক, Google-এর সার্ভারে বারবার অনুরোধ করা সহজভাবে লুপ না করা গুরুত্বপূর্ণ। এই লুপিং আচরণ আপনার ক্লায়েন্ট এবং Google এর মধ্যে নেটওয়ার্ককে ওভারলোড করতে পারে যা অনেক পক্ষের জন্য সমস্যা সৃষ্টি করে।

একটি ভাল পদ্ধতি হল প্রচেষ্টার মধ্যে ক্রমবর্ধমান বিলম্বের সাথে পুনরায় চেষ্টা করা। সাধারণত বিলম্ব প্রতিটি প্রচেষ্টার সাথে একটি গুণক ফ্যাক্টর দ্বারা বৃদ্ধি করা হয়, একটি পদ্ধতি যা এক্সপোনেনশিয়াল ব্যাকঅফ নামে পরিচিত।

উদাহরণস্বরূপ, এমন একটি অ্যাপ্লিকেশন বিবেচনা করুন যা টাইম জোন এপিআইতে এই অনুরোধ করতে চায়:

https://maps.googleapis.com/maps/api/timezone/json?location=39.6034810,-119.6822510&timestamp=1331161200&key=YOUR_API_KEY

নিম্নলিখিত পাইথন উদাহরণটি দেখায় কিভাবে সূচকীয় ব্যাকঅফের সাথে অনুরোধ করা যায়:

import json
import time
import urllib.error
import urllib.parse
import urllib.request

# The maps_key defined below isn't a valid Google Maps API key.
# You need to get your own API key.
# See https://developers.google.com/maps/documentation/timezone/get-api-key
API_KEY = "YOUR_KEY_HERE"
TIMEZONE_BASE_URL = "https://maps.googleapis.com/maps/api/timezone/json"


def timezone(lat, lng, timestamp):

    # Join the parts of the URL together into one string.
    params = urllib.parse.urlencode(
        {"location": f"{lat},{lng}", "timestamp": timestamp, "key": API_KEY,}
    )
    url = f"{TIMEZONE_BASE_URL}?{params}"

    current_delay = 0.1  # Set the initial retry delay to 100ms.
    max_delay = 5  # Set the maximum retry delay to 5 seconds.

    while True:
        try:
            # Get the API response.
            response = urllib.request.urlopen(url)
        except urllib.error.URLError:
            pass  # Fall through to the retry loop.
        else:
            # If we didn't get an IOError then parse the result.
            result = json.load(response)

            if result["status"] == "OK":
                return result["timeZoneId"]
            elif result["status"] != "UNKNOWN_ERROR":
                # Many API errors cannot be fixed by a retry, e.g. INVALID_REQUEST or
                # ZERO_RESULTS. There is no point retrying these requests.
                raise Exception(result["error_message"])

        if current_delay > max_delay:
            raise Exception("Too many retry attempts.")

        print("Waiting", current_delay, "seconds before retrying.")

        time.sleep(current_delay)
        current_delay *= 2  # Increase the delay each time we retry.


if __name__ == "__main__":
    tz = timezone(39.6034810, -119.6822510, 1331161200)
    print(f"Timezone: {tz}")

আপনার সতর্কতা অবলম্বন করা উচিত যে অ্যাপ্লিকেশন কল চেইনে উচ্চতর কোড পুনরায় চেষ্টা না করা যা দ্রুত ধারাবাহিকভাবে অনুরোধের দিকে নিয়ে যায়।

সিঙ্ক্রোনাইজ করা অনুরোধ

Google-এর এপিআই-এ বিপুল সংখ্যক সিঙ্ক্রোনাইজ করা অনুরোধগুলি Google-এর পরিকাঠামোতে ডিস্ট্রিবিউটেড ডিনায়েল অফ সার্ভিস (DDoS) আক্রমণের মতো দেখতে পারে এবং সেই অনুযায়ী আচরণ করা হবে। এটি এড়াতে, আপনাকে নিশ্চিত করতে হবে যে API অনুরোধগুলি ক্লায়েন্টদের মধ্যে সিঙ্ক্রোনাইজ করা হয়নি।

উদাহরণস্বরূপ, একটি অ্যাপ্লিকেশন বিবেচনা করুন যা বর্তমান সময় অঞ্চলে সময় প্রদর্শন করে। এই অ্যাপ্লিকেশনটি সম্ভবত ক্লায়েন্ট অপারেটিং সিস্টেমে একটি অ্যালার্ম সেট করবে যা মিনিটের শুরুতে এটিকে জাগিয়ে দেবে যাতে প্রদর্শিত সময় আপডেট করা যায়। সেই অ্যালার্মের সাথে যুক্ত প্রক্রিয়াকরণের অংশ হিসাবে অ্যাপ্লিকেশনটির কোনো API কল করা উচিত নয় ।

একটি নির্দিষ্ট অ্যালার্মের প্রতিক্রিয়া হিসাবে API কল করা খারাপ কারণ এর ফলে API কলগুলি সময়ের সাথে সমানভাবে বিতরণ না করে এমনকি বিভিন্ন ডিভাইসের মধ্যেও মিনিটের শুরুতে সিঙ্ক্রোনাইজ করা হয়। এটি করার একটি খারাপভাবে ডিজাইন করা অ্যাপ্লিকেশন প্রতিটি মিনিটের শুরুতে স্বাভাবিক মাত্রার ষাট গুণে ট্রাফিকের স্পাইক তৈরি করবে।

পরিবর্তে, একটি সম্ভাব্য ভাল ডিজাইন হল একটি এলোমেলোভাবে নির্বাচিত সময়ে একটি দ্বিতীয় অ্যালার্ম সেট করা। যখন এই দ্বিতীয় অ্যালার্মটি ফায়ার হয় তখন অ্যাপ্লিকেশনটি প্রয়োজনীয় যেকোন API কল করে এবং ফলাফল সংরক্ষণ করে। যখন অ্যাপ্লিকেশনটি মিনিটের শুরুতে তার প্রদর্শন আপডেট করতে চায়, তখন এটি আবার API কল করার পরিবর্তে পূর্বে সংরক্ষিত ফলাফলগুলি ব্যবহার করে। এই পদ্ধতির সাথে, API কলগুলি সময়ের সাথে সমানভাবে ছড়িয়ে পড়ে। আরও, যখন ডিসপ্লে আপডেট করা হচ্ছে তখন API কল রেন্ডারিং করতে দেরি করে না।

মিনিটের শুরুর পাশাপাশি, অন্যান্য সাধারণ সিঙ্ক্রোনাইজেশন সময়গুলিকে লক্ষ্য করা উচিত নয় যাতে লক্ষ্য করা যায় এক ঘন্টার শুরুতে, এবং প্রতিটি দিনের শুরু মধ্যরাতে।

প্রতিক্রিয়া প্রক্রিয়াকরণ

এই বিভাগে আলোচনা করা হয়েছে কিভাবে ওয়েব পরিষেবার প্রতিক্রিয়াগুলি থেকে গতিশীলভাবে এই মানগুলি বের করা যায়।

Google মানচিত্র ওয়েব পরিষেবাগুলি এমন প্রতিক্রিয়াগুলি প্রদান করে যা বোঝা সহজ, কিন্তু ঠিক ব্যবহারকারী বান্ধব নয়৷ একটি কোয়েরি সম্পাদন করার সময়, ডেটার একটি সেট প্রদর্শন করার পরিবর্তে, আপনি সম্ভবত কয়েকটি নির্দিষ্ট মান বের করতে চান। সাধারণত, আপনি ওয়েব পরিষেবা থেকে প্রতিক্রিয়া বিশ্লেষণ করতে চান এবং শুধুমাত্র সেই মানগুলি বের করতে চান যা আপনার আগ্রহের।

আপনি যে পার্সিং স্কিমটি ব্যবহার করেন তা নির্ভর করে আপনি JSON-এ আউটপুট ফেরত দিচ্ছেন কিনা। JSON প্রতিক্রিয়া, ইতিমধ্যে জাভাস্ক্রিপ্ট অবজেক্টের আকারে, ক্লায়েন্টে জাভাস্ক্রিপ্টের মধ্যেই প্রক্রিয়া করা হতে পারে।