現在，讓我們嘗試存取日本郵政的數位地址 API 並取得地址。這真的是 OAuth 嗎？ –@

6.4k VIEWS

很抱歉，我最近身體不舒服，並且有一些空閒時間。在上一篇文章中，我們學習如何取得日本郵政數位地址（digi-ad）並在日本郵政提供的運輸標籤建立應用程式中使用它。這次，我們將嘗試透過 API 來取得它。畢竟，“郵遞區號/數位地址 API”頁面由於它支援 OAuth 2.0 和 OpenID Connect，所以只能這樣做。

取得 Yu-ID Biz

現在，為了存取 Yu-ID API，您必須註冊 Biz 的郵遞區號/數位地址。當您進入註冊頁面時，您將看到此畫面：

用戶名可以稍後更改。輸入適當的名稱後，「註冊」按鈕將變為黑色並可按下，然後按下它。

這將帶您進入組織註冊畫面。看來公司和個體戶都可以申請。對我來說，兩個選項都很好，但我決定選擇具有更多輸入欄位的公司選項。我剛好還擁有一家名為 NAT Consulting LLC 的公司。

完成註冊後，您將進入顯示使用者清單的畫面。

該畫面不僅顯示用戶列表，還顯示「設定」選單，顯示您的組織所做的設置，在「服務」下，左側選單中有一個鏈接，指向有關「郵遞區號和數位地址 API」的頁面和「從數字地址搜尋地址」的頁面。讓我們轉到我們要找的頁面“郵政編碼/數字地址 API”。

單擊打開菜單。

「系統清單」可讓您查看已註冊客戶名單並註冊客戶。

在「測試 AI 憑證」中，您可以顯示 client_id 和 client_secret 以使用測試 API。還有用於測試的 API 參考文件。您需要做的第一件事是建立一個將呼叫測試 API 的客戶端，並且您需要按照此處的說明進行操作。 API 參考如下所示：

「下載」按鈕看起來會下載 OpenAPI 規範，但我無法下載它。我希望這個區域能夠得到修復。

API 參考包含生產 API 參考。

使用指南包括如何處理“數字地址”資料的說明。

發行說明目前為空白。

資料來源包含作為此 API 提供的資料的來源的 CSV 檔案。

現在讓我們嘗試測試 API。

現在，讓我們嘗試存取測試 API，看看如何使用 OAuth 和 OpenID Connect。

獲取訪問令牌

根據文檔，它似乎支持OAuth 2.0 [RFC6749] の客戶端憑證授予好像僅此而已。這樣就獲取到了訪問令牌。通常，存取權杖將在授權標頭（伺服器必須支援）中發送，或作為請求正文中的參數發送，但在此範例中，它以 JSON 的形式在正文中發送。

它是這樣的。

{
"grant_type": "client_credentials",
"client_id": "Test_Client_Identifier_String",
"secret_key": "Test_Secret_Key"
}

OAuth 2.0 中沒有定義這一點。專有規格可以公平地這麼說。順便說一句，如果使用RFC6749中指定的方法發送，則會導致錯誤請求。

但這並不是唯一的獨特之處。在這種情況下，請求必須包含 x-forwarded-for。這也是一個專有擴充。我能理解你的感受，但......順便說一句，沒有具體說明要把什麼放進去。我想你可能輸入了連接到這個客戶端的設備的IP位址。但是，根據 RFC7239，它表示停止使用 x-forwarded-for 並使用 Forwarded。

順便說一下，點擊文件路徑可以顯示 API 端點。

考慮到這一點，我們向測試 API 發送請求，該請求可以從 API 文件中取得。

curl -X POST https://stub-qz73x.da.pf.japanpost.jp/api/v1/j/token \
  -H "Content-Type: application/json" \
  -H "X-Forwarded-For: 64.227.48.220" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "Test_Client_Identifier_String",
    "secret_key": "Test_Secret_Key"
  }'

如果你這樣做，你會得到如下的回應：

{"token":"eyJhbGciOiJSU.中略.TmrM38fAf8cgNm1QAnf-j0YFQA",
"token_type":"jwt",
"expires_in":600,
"scope":"J1"}

存取令牌採用 JWT 格式。裡面是這樣的。

標題

{
  "alg": "RS256",
  "typ": "JWT"
}

Payload

{
  "iss": "JPD",
  "sub": "DGA TOKEN",
  "scope": "J1",
  "clientId": "Biz_DaPfJapanpost_MockAPI_j3QKS",
  "ec_id": "8aeaf147-112f-4127-8cbb-2eff08a8e161",
  "iat": 1742886316,
  "exp": 1742886916
}

它看起來像這樣。哦，類型很奇怪。RFC9068照這個來說，類型應該是at+jwt。

此外，由於 iss 只是一個字串，所以不可能發現 JWK 並因此無法驗證它，但這不是問題，因為是由日本郵政自己執行驗證。我以為sub會包含client_id，但似乎事實並非如此，它是一個固定的字串。

現在，我們嘗試將數字位址解析為位址。

然後，我們使用此存取權杖向搜尋端點發出 OAuth 請求。存取令牌可以在授權標頭中發送。看起來 X-Forwarded-For 仍在發送。測試 API 可讓您搜尋東京千代田區的三個測試數位地址（A3E7FK2、JN2LKS4、QN2GQX6）以及郵遞區號和個人商業郵遞區號。

使用 curl 後它看起來像這樣。

curl -X GET https://stub-qz73x.da.pf.japanpost.jp/api/v1/searchcode/A7E2FK2 \
  -H "Authorization: Bearer eyJhbGci..中略..QAnf-j0YFQA" \
  -H "X-Forwarded-For: 64.227.48.220" \
  -H "Accept: application/json"

然後它會回傳類似這樣的訊息：

{
	"page": 1,
	"limit": 1000,
	"count": 1,
	"searchtype": "dgacode",
	"addresses": [
		{
			"dgacode": "A7E2FK2",
			"zip_code": "100-0005",
			"pref_code": "13",
			"pref_name": "東京都",
			"pref_kana": null,
			"pref_roma": null,
			"city_code": "13101",
			"city_name": "千代田区",
			"city_kana": null,
			"city_roma": null,
			"town_name": "丸の内",
			"town_kana": null,
			"town_roma": null,
			"biz_name": null,
			"biz_kana": null,
			"biz_roma": null,
			"block_name": "２丁目７−２",
			"other_name": "部屋番号：サンプル１",
			"address": "東京都千代田区丸の内２丁目７−２部屋番号：サンプル１",
			"longitude": null,
			"latitude": null
		}
	]
}

嗯，回應不是 OpenID Connect UserInfo 回應，但卻是唯一的。

順便說一下，如果你指定了上述三個以外的數字位址，

{
"request_id":"848f5369-56fb-4488-aecd-b82599a1b2f9",
"error_code":"404-1029-0001",
"message":"該当するデジアドがありませんでした"
}

然後回來。

訪問生產環境

好的，這樣就成功了，現在讓我們嘗試訪問生產環境。

您所做的與測試相同，只有目的地、client_id 和 client_secret 會改變。您可以透過在「系統清單」選單中註冊客戶端來取得生產的client_id和client_secret。

要獲取令牌，請訪問 https://api.da.pf.japanpost.jp/api/v1/j/token 請將其更改為並請求。

curl -X POST https://api.da.pf.japanpost.jp/api/v1/j/token \
  -H "Content-Type: application/json" \
  -H "X-Forwarded-For: 64.227.48.220" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "クライアントID",
    "secret_key": "クライアントシークレット"
  }'

將會傳回一個存取令牌，您可以使用它來發出請求。這將返回上面顯示的 JSON。您也可以指定郵遞區號而不是數位地址。

  curl -X GET https://api.da.pf.japanpost.jp/api/v1/searchcode/6180000 \
  -H "Authorization: Bearer eyJhbGciOiJS..中略..wV0si0TiQ" \
  -H "X-Forwarded-For: 64.227.48.220" \
  -H "Accept: application/json"

するとこんなふうに帰ってきます。

{
  "page": 1,
  "limit": 1000,
  "count": 2,
  "searchtype": "zipcode",
  "addresses": [
    {
      "dgacode": null,
      "zip_code": "6180000",
      "pref_code": "26",
      "pref_name": "京都府",
      "pref_kana": "キョウトフ",
      "pref_roma": "KYOTO",
      "city_code": "26303",
      "city_name": "乙訓郡大山崎町",
      "city_kana": "オトクニグンオオヤマザキチョウ",
      "city_roma": "OTOKUNI-GUN OYAMAZAKI-CHO",
      "town_name": "",
      "town_kana": "",
      "town_roma": "",
      "biz_name": null,
      "biz_kana": null,
      "biz_roma": null,
      "block_name": null,
      "other_name": null,
      "address": null,
      "longitude": null,
      "latitude": null
    },
    {
      "dgacode": null,
      "zip_code": "6180000",
      "pref_code": "27",
      "pref_name": "大阪府",
      "pref_kana": "オオサカフ",
      "pref_roma": "OSAKA",
      "city_code": "27301",
      "city_name": "三島郡島本町",
      "city_kana": "ミシマグンシマモトチョウ",
      "city_roma": "MISHIMA-GUN SHIMAMOTO-CHO",
      "town_name": "",
      "town_kana": "",
      "town_roma": "",
      "biz_name": null,
      "biz_kana": null,
      "biz_roma": null,
      "block_name": null,
      "other_name": null,
      "address": null,
      "longitude": null,
      "latitude": null
    }
  ]
}

摘要

所以，總結一下。

數位廣告轉換 APIRFC6749使用類似於客戶端憑證授予的唯一規範來取得存取令牌。此存取權杖是 JWT，但類型是 RFC9068依說明，不是at+jwt，而是JWT。
現在，使用取得的存取令牌RFC6750以這種格式發送代碼，獲取註冊到數字地址的字串（不一定是地址）。
- 任何字串都可以註冊，例如，你可以註冊一個地址，例如“在一封來自東京的信中：‘你不存在’。它不會出現在鏡子裡，人們也不會注意到它。我悄無聲息地消失了。” 你也可以註冊類似“¹。
我還沒有找到任何類似 OpenID Connect 的東西。
您也可以透過指定郵遞區號而不是數位地址來取得地址。如果有重複，則會在陣列中傳回多個項目。

順便說一句，有很多重複的郵政編碼。據了解，重複件有1,341件。根據物品的不同，它甚至可能來自不同的縣。這是怎麼回事…？

註腳

嗯，OpenID Connect 中的地址聲明也是如此。

取得 Yu-ID Biz

現在讓我們嘗試測試 API。

獲取訪問令牌

現在，我們嘗試將數字位址解析為位址。

訪問生產環境

摘要

註腳

連接

發表評論 取消評論

發表評論取消評論