📘 תיעוד 17

ביצוע קריאות API

עודכן לאחרונה ב-20 באפריל 2026.

אחרי שיוצרים אסימון API, כל בקשות ה-API מאושרות באותו אופן. Cloudflare משתמשת בממשק התקן RFC ↗︎ Authorization: Bearer <API_TOKEN>. דוגמה לבקשה מופיעה למטה.

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID" \
--header "Authorization: Bearer YQSn-xWAQiiEh9qM58wZNnyQS7FUdoqGIUAbrh7T"

לעולם אל תשלחו ואל תשמרו את הסוד של אסימון ה-API בטקסט גלוי. כמו כן, ודאו שלא מכניסים אותו למאגרי קוד, במיוחד ציבוריים.

שקלו להגדיר משתני סביבה עבור מזהה האזור או החשבון, וגם עבור פרטי אימות (לדוגמה, אסימון ה-API).

כדי לעצב פלט JSON לקריאות בשורת הפקודה, אפשר להשתמש בכלי כמו jq, מעבד JSON בשורת הפקודה. למידע נוסף על השגה והתקנה של jq, ראו הורדת jq ↗︎.

הדוגמה הבאה תעצב את פלט ה-JSON של curl באמצעות jq:

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" | jq .

#שימוש ב-API של Cloudflare

כל רכיב ב-API של Cloudflare קבוע למספר גרסה. הגרסה העדכנית היא גרסה 4. כתובת הבסיס היציבה לכל נקודות הקצה של HTTPS בגרסה 4 היא: https://api.cloudflare.com/client/v4/

להנחיה ספציפית על ביצוע קריאות API, ראו את המשאבים הבאים:

• מדור תיעוד המפתחים של המוצר, למדריכי הדרכה.
• תיעוד סכמת ה-API עבור מטעני בקשה ותשובה של כל נקודת קצה.
• ספריות first-party עבור Go ↗︎, TypeScript ↗︎, Python ↗︎, או Terraform של HashiCorp ↗︎.

#פרמטרי שאילתה

לכמה נקודות קצה של Cloudflare יש פרמטרי שאילתה אופציונליים לסינון התוצאות שמתקבלות, כמו List Zones.

כשמוסיפים את פרמטרי השאילתה האלה, ודאו שסוגרים את כתובת ה-URL במירכאות כפולות "" (בדיוק כמו ערכי הכותרות), אחרת קריאת ה-API עלולה להחזיר שגיאה.

curl "https://api.cloudflare.com/client/v4/zones?account.id=$ACCOUNT_ID" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

אפשר לסגור מחרוזות במירכאות בודדות ('') או במירכאות כפולות (""). שימוש במירכאות בודדות מונע החלפת משתנים במעטפות כמו bash. בדוגמה הקודמת, המשמעות היא שמשתני הסביבה $ACCOUNT_ID ו-$CLOUDFLARE_API_TOKEN לא יוחלפו בערכים שלהם.

#עימוד

לפעמים יהיו יותר מדי תוצאות להצגה בגודל העמוד ברירת המחדל, לדוגמה אפשר לקבל את הדברים הבאים:

"count": 1,
"page": 1,
"per_page": 20,
"total_count": 200,

קיימות שתי אפשרויות של פרמטרי שאילתה, שאפשר לשלב כדי לדפדף בין התוצאות.

• page=x מאפשר לבחור עמוד מסוים.
• per_page=xx מאפשר להתאים את מספר התוצאות שמוצגות בעמוד. אם בוחרים יותר מדי, אפשר לקבל timeout.

דוגמה אפשרית היא https://api.cloudflare.com/client/v4/zones/$ZONE_ID/dns_records?per_page=100&page=2.

אפשרויות נוספות:

• order: בחירת המאפיין שלפיו מסדרים.
• direction: או ASC (סדר עולה) או DESC (סדר יורד).

האפשרויות הזמינות יופיעו בסוף result_info של כל נקודות הקצה בתיעוד ה-API.

#ביצוע קריאות API ב-Windows

גרסאות עדכניות של Windows 10 ו-Windows 11 כבר כוללות את כלי curl ↗︎ שמשמש בדוגמאות ה-API בתיעוד המפתחים. אם משתמשים בגרסת Windows אחרת, ראו הורדות Windows ↗︎ באתר curl למידע נוסף על השגה והתקנה של הכלי.

#שימוש בחלון Command Prompt

כדי להשתמש ב-API של Cloudflare עם curl בחלון Command Prompt, חובה להשתמש במירכאות כפולות (") כמפרידי מחרוזות.

בקשת PATCH אופיינית תהיה דומה לבאה:

C:\>curl --request PATCH "https://api.cloudflare.com/client/v4/user/invites/{id}" --header "X-Auth-Email: <EMAIL>" --header "X-Auth-Key: <API_KEY>" --data "{""status"": ""accepted""}"

כדי לבצע escape לתו מירכאות כפולות בגוף הבקשה (לדוגמה, גוף שצוין עם -d או --data בבקשת POST/PATCH), הוסיפו לפניו מירכאות כפולות (") נוספות או תו לוכסן הפוך (\).

כדי לפצל פקודה אחת לשתי שורות או יותר, השתמשו ב-^ כתו המשך שורה בסוף שורה:

C:\>curl --request PATCH ^
"https://api.cloudflare.com/client/v4/user/invites/{id}" ^
--header "X-Auth-Email: <EMAIL>" ^
--header "X-Auth-Key: <API_KEY>" ^
--data "{""status"": ""accepted""}"

#שימוש ב-PowerShell

הערה

Cloudflare ממליצה להשתמש בגרסה היציבה או בגרסת התצוגה המקדימה העדכנית ביותר של PowerShell. למידע נוסף, ראו התקנת PowerShell ב-Windows ↗︎.

ל-PowerShell יש cmdlets ייעודיים (Invoke-RestMethod ו-ConvertFrom-Json) לביצוע קריאות REST API ולטיפול בתשובות JSON. התחביר של ה-cmdlets האלה שונה מדוגמאות ה-curl שבתיעוד המפתחים.

הדוגמה הבאה משתמשת ב-cmdlet Invoke-RestMethod:

Invoke-RestMethod -URI "https://api.cloudflare.com/client/v4/zones/$Env:ZONE_ID/ssl/certificate_packs?ssl_status=all" -Method 'GET' -Headers @{'X-Auth-Email'=$Env:CLOUDFLARE_EMAIL;'X-Auth-Key'=$Env:CLOUDFLARE_API_KEY}

result      : {@{id=78411cfa-5727-4dc1-8d4a-773d01f17c7c; type=universal; hosts=System.Object[];
              primary_certificate=c173c8a1-9724-4e96-a748-2c4494186098; status=active; certificates=System.Object[];
              created_on=2022-12-09T23:11:06.010263Z; validity_days=90; validation_method=txt;
              certificate_authority=lets_encrypt}}
result_info : @{page=1; per_page=20; total_pages=1; count=1; total_count=1}
success     : True
errors      : {}
messages    : {}

הפקודה מניחה שמשתני הסביבה ZONE_ID, CLOUDFLARE_EMAIL ו-CLOUDFLARE_API_KEY הוגדרו מראש. למידע נוסף, ראו משתני סביבה.

כברירת מחדל, הפלט יכיל רק את הרמה הראשונה בהיררכיית אובייקט ה-JSON (בדוגמה למעלה, התוכן של אובייקטים כמו hosts ו-certificates לא מוצג). כדי להציג רמות נוספות ולעצב את הפלט כמו כלי jq, אפשר להשתמש ב-cmdlet ConvertFrom-Json ולציין את העומק המרבי הרצוי (כברירת מחדל, 2):

Invoke-RestMethod -URI "https://api.cloudflare.com/client/v4/zones/$Env:ZONE_ID/ssl/certificate_packs?ssl_status=all" -Method 'GET' -Headers @{'X-Auth-Email'=$Env:CLOUDFLARE_EMAIL;'X-Auth-Key'=$Env:CLOUDFLARE_API_KEY} | ConvertTo-Json -Depth 5

{
	"result": [
		{
			"id": "78411cfa-5727-4dc1-8d4a-773d01f17c7c",
			"type": "universal",
			"hosts": ["*.example.com", "example.com"],
			"primary_certificate": "c173c8a1-9724-4e96-a748-2c4494186098",
			"status": "active",
			"certificates": [
				{
					"id": "c173c8a1-9724-4e96-a748-2c4494186098",
					"hosts": ["*.example.com", "example.com"],
					"issuer": "LetsEncrypt",
					"signature": "ECDSAWithSHA384",
					"status": "active",
					"bundle_method": "ubiquitous",
					"zone_id": "<ZONE_ID>",
					"uploaded_on": "2023-02-02T11:20:25.403338Z",
					"modified_on": "2022-12-08T00:26:15.577555Z",
					"expires_on": "2023-03-07T23:26:12.000000Z",
					"priority": null
				}
			],
			"created_on": "2022-12-09T23:11:06.010263Z",
			"validity_days": 90,
			"validation_method": "txt",
			"certificate_authority": "lets_encrypt"
		}
	]
	// (...)
}

טיפול של ConvertFrom-Json בערכי DateTime

ה-cmdlet ConvertTo-Json מנסה להמיר מחרוזות שמעוצבות כחותמות זמן לערכי DateTime, לפי הפורמט המדויק במחרוזת. לפרטים על ההתנהגות הזו, ראו את ההערות בתיעוד ConvertFrom-Json ↗︎.

אפשר גם להשתמש בכלי curl ב-PowerShell. ב-PowerShell, curl הוא כינוי ל-cmdlet Invoke-WebRequest, שתומך בתחביר שונה מכלי curl הרגיל. כדי להשתמש ב-curl, הזינו curl.exe במקום זאת.

בקשת PATCH אופיינית עם curl תהיה דומה לבאה:

curl.exe --request PATCH "https://api.cloudflare.com/client/v4/user/invites/{id}" --header "Authorization: Bearer $Env:CLOUDFLARE_API_TOKEN" --data '{\"status\": \"accepted\"}'

כדי לבצע escape לתו מירכאות כפולות (") בגוף הבקשה (שצוין עם -d או --data), הוסיפו לפניו מירכאות כפולות (") נוספות או לוכסן הפוך (\). חובה לבצע escape למירכאות כפולות גם כשמשתמשים במירכאות בודדות (') כמפרידי מחרוזות.

כדי לפצל פקודה אחת לשתי שורות או יותר, השתמשו בתו backtick (`) כתו המשך שורה בסוף שורה:

curl.exe --request PATCH `
"https://api.cloudflare.com/client/v4/user/invites/{id}" `
--header "X-Auth-Email: $Env:CLOUDFLARE_EMAIL" `
--header "X-Auth-Key: $Env:CLOUDFLARE_API_KEY" `
--data '{\"status\": \"accepted\"}'

#משתני סביבה

אפשר להגדיר משתני סביבה לערכים שחוזרים בין פקודות, כמו מזהה האזור או החשבון. משך החיים של משתנה סביבה יכול להיות סשן המעטפת הנוכחי, כל הסשנים העתידיים של המשתמש הנוכחי, או אפילו כל הסשנים העתידיים של כל המשתמשים במחשב שבו מגדירים אותם.

אפשר גם להשתמש במשתני סביבה לשמירת פרטי אימות (אסימון API, מפתח API ודוא"ל) ולשימוש חוזר בהם בפקודות שונות. ודאו שמגדירים את הערכים האלה בהיקף הקטן ביותר האפשרי (או רק סשן המעטפת הנוכחי, או כל הסשנים החדשים של המשתמש הנוכחי).

ההליך להגדרה ולהפניה למשתני סביבה תלוי בפלטפורמה ובמעטפת.

#הגדרת משתנה סביבה

כדי להגדיר משתנה סביבה ZONE_ID לסשן המעטפת הנוכחי, הריצו את הפקודה הבאה:

export ZONE_ID='f2ea6707005a4da1af1b431202e96ac5'

כדי להגדיר את המשתנה לכל סשני המעטפת החדשים של המשתמש הנוכחי, הוסיפו את הפקודה למעלה בסוף קובץ ההגדרות של המעטפת (לדוגמה, ~/.bashrc עבור מעטפת bash ו-~/.zshrc עבור מעטפת zsh).

כדי להגדיר משתנה סביבה ZONE_ID לסשן PowerShell הנוכחי, הריצו את הפקודה הבאה:

$Env:ZONE_ID='f2ea6707005a4da1af1b431202e96ac5'

כדי להגדיר את משתנה הסביבה לכל סשני PowerShell החדשים של המשתמש הנוכחי, הגדירו את המשתנה בפרופיל PowerShell. אפשר לקבל את הנתיב לפרופיל PowerShell על ידי הרצת echo $PROFILE.

לחלופין, הגדירו את המשתנה לכל סשני PowerShell החדשים של המשתמש הנוכחי באמצעות המתודה SetEnvironmentVariable() של המחלקה System.Environment. לדוגמה:

[Environment]::SetEnvironmentVariable("ZONE_ID", "f2ea6707005a4da1af1b431202e96ac5", "User")

הרצת הפקודה הזו לא תשפיע על הסשן הנוכחי. יהיה צורך לסגור ולהתחיל סשן PowerShell חדש.

כדי להגדיר משתנה סביבה ZONE_ID לסשן Command Prompt הנוכחי, הריצו את הפקודה הבאה:

set ZONE_ID=f2ea6707005a4da1af1b431202e96ac5

כדי להגדיר משתנה סביבה לכל סשני Command Prompt העתידיים של המשתמש הנוכחי, הריצו את הפקודה הבאה:

setx ZONE_ID f2ea6707005a4da1af1b431202e96ac5

הרצת הפקודה הזו לא תשפיע על החלון הנוכחי. יהיה צורך להריץ את הפקודה set, או לסגור ולהתחיל חלון Command Prompt חדש.

#הפניה למשתנה סביבה

כשמפנים למשתנה סביבה בפקודה, הוסיפו קידומת $ לשם המשתנה (לדוגמה, $ZONE_ID). ודאו שהמחרוזת המלאה שמפנה למשתנה לא נתונה במירכאות (אם אין בה רווחים) או סגורה במירכאות כפולות ("").

לדוגמה:

curl "https://api.cloudflare.com/client/v4/zones/$ZONE_ID" \
--header "Authorization: Bearer $CLOUDFLARE_API_TOKEN"

כשמפנים למשתנה סביבה בפקודה, הוסיפו קידומת $Env: לשם המשתנה (לדוגמה, $Env:ZONE_ID). ודאו שהמחרוזת המלאה שמפנה למשתנה לא נתונה במירכאות או סגורה במירכאות כפולות ("").

לדוגמה:

Invoke-RestMethod -URI "https://api.cloudflare.com/client/v4/zones/$Env:ZONE_ID" -Method 'GET' -Headers @{'Authorization'="Bearer $Env:CLOUDFLARE_API_TOKEN"}

כשמפנים למשתנה סביבה בפקודה, סגרו את שם המשתנה בתווי % (לדוגמה, %ZONE_ID%).

לדוגמה:

curl "https://api.cloudflare.com/client/v4/zones/%ZONE_ID%" --header "Authorization: Bearer %CLOUDFLARE_API_TOKEN%"