將我的資料分享給第三方

為了符合目前的北美能源標準委員會 （NAESB） 能源服務提供商介面 （ESPI） 授權標準，PG&E 已實施 OAuth 2.0 授權架構，以授權資料存取。下圖說明客戶如何啟動授權、選擇範圍參數，然後提交授權。

除了以下資訊以外的其他參考資料：

下載 ESPI OAuth 2.0 序列圖 （PDF， 193 KB）
在 Github 檢視綠色按鈕資料 SDK

注意：對於 Community Choice 彙總器，只需要 client_access_token 即可要求資料 （透過 2-Legged OAuth），且不適用以下項目。

在第三方網站啟動授權

若要開始由第三方網站授權，如上圖所示，授權代碼要求是透過將客戶的瀏覽器從您的第三方網站重新導向至 PG&E 的授權伺服器授權端點 URL，並具有適當的要求參數，如下所示。重新導向時，客戶將會收到驗證用的 PG&E 登入頁面，接著是授權資料存取您第三方的授權頁面：

authorizationServerAuthorizationEndpoint URI （含要求參數）
https://sharemydata.pge.com/myAuthorization?client_id=A1b2C3&redirect_uri={redirect_uri}&response_type=code&state={optionalState}

• 強制要求參數：
  • client_id = 來自您共用我的資料註冊里程碑（即 client_id/client_secret 配對）的客戶 ID。
  • redirect_uri = 您在共用我的資料註冊中指定的重新導向 URL（URL 必須相符）。
    注意： 我們建議將 URL 編碼套用到 redirect_uri，如下圖所示。
  • response_type = 代碼（靜態值）
• 選擇性要求參數（們）：
  • state = OAuth 2.0 標準所允許的選擇性不透明狀態參數，該參數會連同授權碼一起傳回，以協助維持狀態。例如，第三方可能會使用狀態參數來唯一識別客戶發起，並防止跨網站偽造。
  • login={guest} 提供選項供第三方將客戶重新導向至 PG&E 的 My Energy 登入或訪客存取標籤，作為線上授權流程的一部分。

範例：驗證代碼要求

取得：https://sharemydata.pge.com/myAuthorization?client_id=A1b2C3&redirect_uri=https%3A%2F%2Fthirdparty.com%2FredirectUrl&response_type=code&state=pge12advertisement

注意：上面的 redirect_uri 參數範例已套用 URL 編碼（即 https://thirdparty.com/redirectUrl 的 URL 編碼）

如果您按上述方式提出有效請求，且客戶成功驗證並授權，則客戶隨後將重新導向至具有授權代碼、（授權）範圍參數和可選狀態參數（如果作為授權請求的一部分提供）的 redirect_uri，具體如下：

https://thirdparty.com/redirectUrl?authorization_code=7afc7c4f-778a-4ad8-8337-5e19218a2219&scope=FB=1_3_8_13_14_18_19_31_32_35_37_ 38_39_40_4_5_10_15_16_46_47；AdditionalScope=Usage_Billing_Basic_Account_ProgramEnrollment ；IntervalDuration=900_3600；BlockDuration=每日；HistoryLength={3P Registered historical length}；AccountCollection={count of authorizedSAs}；BR={ThirdPartyID}；dataCustodianId=PGE &state=pge12廣告

注意：授權代碼為短期（600 秒內到期），之後必須交換為存取令牌/重新整理令牌組，以完成授權並允許持續的資料存取。請參閱下一節（第 2 節），瞭解存取金鑰/重新整理金鑰要求的詳細資料。

上述（授權）範圍參數作為對授權代碼請求、存取令牌請求以及授權 API 的回應的一部分予以返回。此範圍參數允許傳達客戶授權的最終範圍。具體而言，範圍參數包括對應至 PG&E 所支援的資料群組客戶授權選擇（例如，“使用”、“計費”、“基本”、“帳戶”、“程式註冊”）的“額外範圍”值。範圍參數值會依據下列參考文件進一步擷取：下載支援的功能模組範圍字串對應 按一下至 2.0 （PDF， 222 KB）。

錯誤情境

第三方實施錯誤：如果在請求授權代碼時 client_id 或 redirect_uri 的必要請求參數無效或缺失，則客戶將看到解釋性訊息以及標準的 HTTP 400 系列錯誤。同樣地，如果 response_type 的必要要求參數遺失或無效，則系統會使用 OAuth 2.0 定義的 "invalid_request" 錯誤參數將客戶重新導向回您的 redirect_uri，如果這是原始授權代碼要求中第一次提供，則會選擇狀態參數。

拒絕授權的客戶：當第三方將客戶重新導向至 PG&E 進行授權時，客戶可以選擇透過登入頁面和授權頁面的“取消”按鈕拒絕。在這種情況下，系統會使用附加的 OAuth 2.0 定義的 "access_denied" 錯誤參數，將客戶重新導向回您的 redirect_uri，以表示客戶拒絕授權。此外，如果作為原始授權碼請求的一部分而先提供選擇性州參數，則將傳回。

在 PG&E 啟動授權

當客戶從 PG&E 的客戶入口網站 "您的帳戶" 開始，然後瀏覽至 Share My Data 登陸頁面時，系統會顯示已註冊和可見的第三方的下拉式清單。如上圖第二圖所示，在客戶從已註冊的第三方清單中選擇第三方並選擇“下一步”時，該客戶將被重新導向到第三方的已註冊“第三方入口網站 URI”，屆時客戶可以繼續進行前節所述的第三方發起的 OAuth 流程。

注意：有些第三方詢問如何簡化此使用案例的客戶體驗 （即 PG&E 網站上啟動的授權），因此在從下拉選單中選擇第三方時，似乎直接將他們帶往授權頁面。為了促進此類客戶體驗，第三方可以選擇將其第三方入口網站 URI（透過共用我的資料管理註冊頁面）設定為自動將客戶重新導向回 PG&E 的端點，作為授權代碼請求的一部分。自動重新導向回 PG&E 的授權伺服器授權端點後，客戶將略過客戶登入頁面（因為他們已經登入），並直接前往授權頁面。對於在 2018 年 6 月底發佈 Share My Data Click Thru 2.0 之前註冊的某些第三方，只需將第三方入口網站 URI 定義為等於不再使用的“第三方範圍選擇螢幕” URI（未來發佈中要淘汰的欄位）即可完成。

相反地，有些第三方可能希望在客戶要求授權碼之前重新導向到他們的第三方入口網站 URI 時，首先進行互動和篩選，因此上述方法只是建議。

若要取得存取密碼卡，請使用收到的授權碼，並按照下述方式使用要求參數致電以下端點。如上所述，授權碼為簡式，將在 10 分鐘（600 秒）後過期，因此請確保在收到授權碼時立即要求使用金鑰。

authorizationServerAuthorizationEndpoint：https://api.pge.com/datacustodian/oauth/v2/token

• 強制要求參數：
  • grant_type = authorization_code（靜態值）
  • 代碼 = 回應授權代碼請求而收到的授權代碼
  • redirect_uri = 您在共用我的資料註冊中指定的重新導向 URL（URL 必須相符）。
    注意：與授權碼請求一樣，我們建議將 URL 編碼套用於 redirect_uri。

範例：存取金鑰要求
POST： https://api.pge.com/datacustodian/oauth/v2/token?grant_type=authorization_code&code={authorizationcode}&redirect_uri={redirect_uri}

新增基本授權標頭參數，並使用 Base64 編碼套用的 "clientID：clientSecret"

注意： clientId：clientSecret 值對應於您共用我的資料註冊里程碑中所提供的 clientID 值。
標題參數格式如下：
參數名稱：授權
參數值：基本 "base64encoded string"

成功的回應將如下所示：

＜回應 xmlns="https：//api.第 頁com/datacustodian/oauth/v2/token">
774ff105-7ad5-40c8-a6ec-f60675dc0e41
3600
998c6654-5b3b-4385-af4f-4e5c46c1bb04
scope=FB=1_3_8_13_14_18_19_31_32_35_37_38_39_40_4_5_10_15_16_46_47AdditionalScope=Usage_Billing_Basic_Account_ProgramEnrollment；間隔持續時間=900_3600；BlockDuration=每日；HistoryLength={3P 註冊歷史長度}；AccountCollection={授權 SA 的數量}；BR={ThirdPartyID}；dataCustodianId=PGE
資源URI：{資源URI}，例如： https：//api.第 頁com/GreenButtonConnect/espi/1_1/resource/Subscription/{subscriptionID}
authorizationURI：{AuthorizationURI}，例如： https：//api.第 頁com/GreenButtonConnect/espi/1_1/resource/Authorization/{authorizationID}
customerResourceURI：{customerResourceURI}，例如：https：//api.第 頁com/GreenButtonConnect/espi/1_1/resource/Batch/RetailCustomer/{RetailCustomerID}
Bearer

注意：存取密碼卡會在 3600 秒（1 小時）後到期，而對應的重新整理密碼卡則會在 1 年後到期。有關取得新的存取金鑰/重新整理金鑰配對的詳細資訊，請參閱下一節 3。

儲存存取權限並重新整理權杖對。
若要要求初始歷史資料和持續的每日資料，請訪問資料存取 。

根據最佳做法，存取金鑰是短期金鑰（1 小時），而對應的重新整理金鑰是長期金鑰（1 年），您可以在存取金鑰過期時用來取得新的存取金鑰/重新整理金鑰組合。若要為現有的未過期授權取得新的 Access Token 和 Refresh Token 配對，請使用 "current Refresh Token"，並按下述參數致電以下端點。

authorizationServerAuthorizationEndpointhttps://api.pge.com/datacustodian/oauth/v2/token ？grant_type= refresh_token&refresh_token={current_refresh_token}

範例：重新整理權杖要求
POST：https://api.pge.com/datacustodian/oauth/v2/token?grant_type= refresh_token&refresh_token={current_refresh_token}

新增基本授權標頭參數，並使用 Base64 編碼套用的 "clientID：clientSecret"

注意： clientId：clientSecret 值對應於您共用我的資料註冊里程碑中所提供的 clientID 值。
標題參數格式如下：
參數名稱：授權
參數值：基本 "base64encoded string"

成功的回應會像這樣：
{
"access_token"： "677e6ef8-1e1a-43f0-85b8-5692fcbc72b2"，
"token_type"："無記名"，
"到期_in"： 3600，
"refresh_token"： "0eef9a9f-60c6-40bb-b33f-910e322c0298"，
"範圍"： "scope=FB=1_3_8_13_14_18_19_31_32_35_37_38_39_40_4_5_10_15_16_46_47；AdditionalScope=Usage_Billing_Basic_Account_
Program註冊；間隔持續時間=900_3600；BlockDuration=每日；HistoryLength={3P 註冊歷史長度}；AccountCollection={授權 SA 的數量}；BR={ThirdPartyID}；dataCustodianId=PGE"，
"resourceURI"： "https：//api.第 頁com/GreenButtonConnect/espi/1_1/resource/Batch/Subscription/test "，
"授權URI"： "https：//api.第 頁com/GreenButtonConnect/espi/1_1/resource/Authorization/test "
}

注意：同樣，客戶存取金鑰是短期金鑰（1 小時），而其對應的重新整理金鑰是長期金鑰（1 年），您可以在客戶存取金鑰到期時用來取得新的客戶存取金鑰/重新整理金鑰組。若要取得新的用戶端存取金鑰/重新整理金鑰組，請參考上述相同步驟。

客戶將能夠透過執行下列動作來更新其授權：

• 從授權中移除服務 ID
• 延長授權期限的結束日期
• 取消授權

注意：客戶只能透過登入其線上 PG&E 帳戶並遵循必要步驟，來變更授權。如果採取任何這些行動，我們將透過您在註冊時提供的通知 URI 通知您。

有管理和檢視客戶授權詳細資料的選項：

• 您可以在第三方層級 （關於所有授權的詳細資訊） 的 https://api.pge.com/GreenButtonConnect 或 /espi/1_1/resource/Authorization 的個別客戶授權層級，使用 client_access https://api.pge.com/GreenButtonConnect_token 呼叫授權 API （http GET operation）。
• 此外，您也可以透過第三方入口網站登入您的 Share My Data 帳戶，並輸入您要搜尋的授權訂閱 ID，以手動方式檢視個別授權詳細資料。

如果您不想再存取與授權相關的資料，可選擇取消授權的方法：

• 您可以在 https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/{AuthorizationID} 使用 client_access_token 呼叫授權撤銷 API （http DELETE 操作）。
• 或者，您可以透過第三方入口網站登入您的 Share My Data 帳戶，並輸入您想要取消的授權的訂閱 ID，以手動方式取消授權。

注意：客戶將收到通知，告知您已選擇取消其授權。此外，一旦取消授權，便無法撤銷操作。

• PG&E 將傳送通知至您在註冊時提供的通知 URI。通知包含對應於已預先封裝資料的 URI，可供您返回，並在提供的 URL 上要求。資料已預先封裝，並在以下兩種情況下發送通知：（1） 您已在註冊檔案中選擇“資料已就緒時通知我”，在這種情況下，我們將把最新的每日資料與過去日期的任何更正進行封裝，或者（2）您提前提出了一個臨時非同步請求，請求的資料現已準備就緒。
• 情境 1 說明於 "DATA ACCESS：以下資料存取方法圖表中的每日訂閱部分，情境 2 顯示在資料存取下：下方相同圖表的 AD HOC REQUEST （ASYNCHRONOUS）" 部分。

請記住，在資料要求中使用的存取金鑰、用戶端存取金鑰及其對應的重新整理金鑰的存留時間。根據最佳做法，存取金鑰是短期金鑰（1 小時），而重新整理金鑰是長期金鑰（1 年），您可以在存取金鑰過期時用來取得新的存取金鑰/重新整理金鑰組合。同樣地，用戶端存取金鑰是短期金鑰（1 小時），而其對應的重新整理金鑰是長期金鑰（1 年），您可以在用戶端存取金鑰過期時用來取得新的用戶端存取金鑰/重新整理金鑰組。如需取得新金鑰組的詳細資訊，請參閱授權詳細資料標籤中的步驟 3，要求新的存取權杖。 前往授權詳細資料

若客戶授權您接收"帳戶資訊"（帳戶 ID、服務協議 ID 和服務開始日期）和/或"基本資訊"（即客戶名稱和服務地址），則您可以透過 ESPI 定義的 RetailCustomer API 索取此類客戶資訊，該 API 的資料符合上述提供的架構，reakiseCustomer.xsd。

同步（標準和 EEF 第三方）

要求客戶資料的一種方法是使用同步 API 要求客戶資料的單一客戶授權客戶資訊 （即零售客戶）：

同步要求 URL 範例：https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/RetailCustomer/{RetailCustomerID}

RetailCustomerID = 您在 OAuth 授權序列結束時收到的 RetailCustomerID，以取得存取權杖。RetailCustomerID 是 Token 回應中 CustomerResourceUri 路徑參數的一部分。（RetailCustomerID=訂閱ID）

HTTP 標頭 = 授權：承載 {此授權的存取權杖}

回應 = 您將同步回傳該 RetailCustomerID 的資料。資料符合 RetailCustomer.xsd

注意：同步零售客戶 API 位於個別零售客戶層級，對應於單一客戶授權。

供參考：下面的階層圖顯示了在建模 PG&E 客戶資料時 ESPI 資料元素的關係階層。

您也可以透過非同步 API 要求客戶資料，以要求取得您所有客戶資料 （亦即零售客戶） 之客戶資訊。

為支援非同步要求，您的應用程式將需要支援我們將向您發送的通知發佈（根據您在註冊時提供的通知 URL）。

非同步要求 URL 範例：
https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/BulkRetailCustomerInfo/{BulkID}

大量 ID = 在註冊測試期間擷取的應用程式資訊資源中提供的大量 ID。（批量 ID=客戶 ID）

HTTP 標頭 = 授權：認證 {註冊測試期間擷取用戶端存取權杖}

回應 = HTTP 狀態代碼 202 （這是一個非同步請求，當資料就緒時，回應將發佈到通知 URL）。資料準備好後，我們會將通知發佈至您提供的通知 URI，其中包含您的應用程式可以返回以取得預先包裝的 URL 承載。通知後範例如下所示

https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/BulkRetailCustomerInfo/{BulkID}？correlationID={correlationID}

使用用戶端存取權杖在上述 URL 上執行 GET 以取得資料。

供參考：下面的階層圖顯示了在建模 PG&E 客戶資料時 ESPI 資料元素的關係階層。

最後，您可以使用每日訂閱模式取得每日最新客戶資訊 （亦即，在註冊時選取 "通知我資料已就緒 （每日）" 核取方塊）。

為支援每日訂閱模式，您的應用程式將需要支援我們將向您發送的通知後（根據您在註冊時提供的通知 URL）。

資料準備好後，我們會將通知發佈至您提供的通知 URI，其中包含您的應用程式可以返回以取得預先包裝的 URL 承載。通知後範例如下所示：

https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/BulkRetailCustomerInfo/{BulkID}？correlationID={correlationID}

使用用戶端存取權杖在上述 URL 上執行 GET 以取得資料。

以下階層圖顯示建模 PG&E 客戶資料時 ESPI 資料元素的關係階層，以供參考。

若客戶授權您接收 "Usage Information" 和/或 "Billing Information"，則您可以透過訂閱 API 索取此資料，該 API 的資料符合上述提供的架構 espiDerived.xsd。

同步臨時請求（標準和 EEF 第三方）

若要要求歷史資料 （包括間隔使用資料和帳單資料），其中一種方法是使用同步 API，並在 Zulu 時間內包含適當的開始和結束日期要求參數。

同步請求 URL 範例：
https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Subscription/{SubscriptionID}/UsagePoint/{UsagePointID}？published-min={startDate}&published-max={endDate}

published-min = 將套用至此資料擷取要求的開始日期。日期以 Zulu time of yyyy-MM-ddTHH：mm：ssZ 表示（IETC RFC 3339 格式）

published-max = 將套用至此資料擷取要求的結束日期。日期以 Zulu time of yyyy-MM-ddTHH：mm：ssZ 表示（IETC RFC 3339 格式）

注意：對於接受發佈-最大和發佈-最小日期參數的 API 請求，預設值為 T-1（請求日期減 1 天）。對於使用摘要請求（例如，.../espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint/{UsagePointID}/UsageSummary），我們建議提供 30 天或更長時間的範圍，以確保有與該期間重疊的可用帳單，否則不會傳回任何資料。

訂閱 ID = 您在 OAuth 授權序列結束時收到的訂閱 ID，以取得存取權杖。訂閱 ID 是 Token 回應中 resourceURI 參數的一部分。（訂閱 ID=零售客戶 ID）

UsagePointID = 上述訂閱 ID 下的 UsagePoint。您可以撥打以下 API URL 並在授權標題中提供該訂閱的存取權杖，以取得特定訂閱的所有使用點數：https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Subscription/{SubscriptionID}/UsagePoint

HTTP 標頭 = 授權：此訂閱的證卡 {存取權杖}

回應 = 您將在請求的期間同步返回該使用點的資料。它將同時包含間隔使用資料 （） 和帳單資料 （）。

同步使用 API （如 URL 構造所指示，以使用點 ID 結尾） 位於個別使用點層級 （即服務合約層級），因此應用程式會透過屬於特定客戶授權 （即訂閱） 的每個使用點 ID 循環要求。

對同步要求的回應會同時傳回與要求日期範圍相關聯的間隔資料 （低於），以及與要求日期範圍 （低於） 重疊的任何每月使用總數和帳單。

• 間隔讀取包含間隔 （15 分鐘/小時） 電力使用量和間隔 （每日） 氣體使用量資料
• 使用情況摘要包含每月使用情況總計和帳單詳情（如經授權）

在回覆中，您會看到對應至 ESPI 資料元素對應表的資料元素

以下階層圖顯示建模 PG&E 客戶資料時 ESPI 資料元素的關係階層，以供參考。

以下是有關這些資料元素的一些重要說明：

• 間隔封鎖為 1 天
• 間隔讀取 （間隔區塊下方） 包含實際的 15 分鐘/小時電力使用值和每日瓦斯使用值
• 對於現場發電（例如太陽能）的電氣客戶，flowDirection 元件會指示已交付（供應）和已接收（發電）的使用資料。對於配置為僅讀取淨使用量（即現場無代數）的儀表的客戶，flowDirection 元素表示使用量為淨量（已交付差異減去接收差異）：
  • 流量方向 1 = 已傳送 （供應給客戶的能源）
  • 19 的流量方向 = 已收到 （淨發電流回 PG&E 網格）。（注意，值為絕對值）
  • 4 的流量方向 = 淨（已交付減 - 已接收）
• 特別注意十倍數乘數和計量單位（uom）的功率，以確保正確讀取使用情況

批次訂閱（標準和 EEF 第三方）

您也可以透過非同步 API，針對屬於單一客戶之使用/帳單資料 （即訂閱） 授權的所有使用點，要求使用資料。

為支援臨時非同步請求（即一次使用多個使用點），您的應用程式將需要支援我們將向您發送的通知後（根據您在註冊時提供的通知 URL）

非同步要求 URL
範例 https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Subscription/{SubscriptionID}？published-min={startDate}&published-max={endDate}

訂閱 ID = 您在 OAuth 序列結束時收到的訂閱 ID，以取得存取權杖。訂閱 ID 是 Token 回應中 resourceURI 參數的一部分

published-min = 將套用至此資料擷取要求的開始日期。（RFC 3339 格式 zulu 時間。yyyy-MM-ddTHH：mm：ssZ）

published-max = 將套用至此資料擷取要求的結束日期。（RFC 3339 格式 zulu 時間。yyyy-MM-ddTHH：mm：ssZ）

HTTP 標頭 = 授權：此訂閱的證卡 {存取權杖}

回應 = HTTP 狀態代碼 202 （這是一個非同步請求，當資料就緒時，回應將發佈到通知 URL）

資料準備好後，我們將傳送通知給您提供的通知 URI，其中包含您的應用程式可以返回以取得預先包裝的 URL 承載。通知後範例如下所示：

＜？xml version="1.0" encoding="UTF-8"？＞

https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Subscription/{SubscriptionID}？correlationID={correlationID}

使用 Access 權杖在上述 URL 上執行 GET 以取得資料。這將包含請求期間的間隔使用資料 （） 以及帳單資訊 （）。

批次訂閱 （標準和 EEF 第三方）
您也可以透過批次非同步 API，針對所有客戶對使用/計費資料 （即訂閱） 的授權來要求使用和計費資訊。

批次大量要求 URL
範例 https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Bulk/{BulkID}？published-min={startDate}&publishedmax={endDate}

大量 ID = 在註冊測試期間擷取的應用程式資訊資源中提供的大量 ID。（批量 ID=客戶 ID）

published-min = 將套用至此資料擷取要求的開始日期。（RFC 3339 格式 zulu 時間。yyyy-MM-ddTHH：mm：ssZ）

published-max = 將套用至此資料擷取要求的結束日期。（RFC 3339 格式 zulu 時間。yyyy-MM-ddTHH：mm：ssZ）

HTTP 標頭 = 授權：承載 {用戶端存取權杖}

回應 = HTTP 狀態代碼 202 （這是一個非同步請求，當資料就緒時，回應將發佈到通知 URL）

資料準備好後，我們將傳送通知給您提供的通知 URI，其中包含您的應用程式可以返回以取得預先包裝的 URL 承載。通知後範例如下所示：

＜？xml version="1.0" encoding="UTF-8"？＞

https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Bulk/{BulkID}？correlationID={correlationID}

使用 Access 權杖在上述 URL 上執行 GET 以取得資料。這將包含請求期間的間隔使用資料 （） 以及帳單資訊 （）。

最後，您可以使用每日訂閱模式取得最新的使用和帳單資訊，包括客戶授權期間過去日期的更正（即在註冊時勾選“通知我為資料已就緒（每日）”核取方塊）。

為支援每日訂閱模式，您的應用程式將需要支援我們將向您發送的通知後（根據您在註冊時提供的通知 URL）。

資料準備好後，我們將傳送通知給您提供的通知 URI，其中包含您的應用程式可以返回以取得預先包裝的 URL 承載。通知後範例如下所示：

＜？xml version="1.0" encoding="UTF-8"？＞

https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/Bulk/{BulkID}？correlationID={correlationID}

使用 Access 權杖在上述 URL 上執行 GET 以取得資料。這將包含請求期間的間隔使用資料 （） 以及帳單資訊 （）。

2023 年 3 月 20 日

新功能：

1. 發佈新的 API HTTP 回應代碼 （204），用於同步和非同步 API 呼叫，以指示何時沒有可用於請求範圍的資料。
2. 支援 x-transaction header 標籤，支援在要求的檔案準備就緒時，透過將此值連同關聯 ID 傳回來連結 PG&E 對特定非同步 API 呼叫的回應。
3. 透過為多個儀表至單一服務協議情境提供電間隔資料，改善了 UsagePoint/MeterReadingID API 的額外資料精細度。
4. 為預估間隔資料的讀取品質指標值提供額外的清晰度，以描述該間隔使用的估計類型。表示已套用估計邏輯的新值如下：
   
   

5. RQI 值和說明

   0 - 有效：已通過所有必要驗證檢查並全部通過或經過驗證的資料

   7 - 手動編輯：由人員取代或核准

   8 - 使用參考日估計：資料值被使用相同類型測量的歷史資料分析機器計算值取代

   9 - 使用線性插補估計：資料值是根據前後的讀數使用線性插補計算

   10 - 可疑：一項或多項檢查未通過的資料

   11 - 衍生：已計算 （使用邏輯或數學運算） 的資料，不一定直接測量

   12 - 預測（預測）：已計算為預測或預測未來讀數的資料

   13 - 混合：表示此讀數的品質具有混合特性

   14 - 原始：未經過驗證、編輯和估計流程的資料。備註 MV90 儀錶 RQI 指示燈將維持在 14 的狀態，作為最終 RQ 狀態

   15 - 天氣標準化：已調整數值以考慮天氣，比較不同氣候中的使用情況

   16 - 其他：指明特性適用於定義者以外的其他特性

   17 - 已驗證：已驗證且可能依據核准程序編輯和/或估計的資料

   18 - 已驗證：資料未通過至少一項必要的驗證檢查，但被判定為代表實際使用情形

   19 - 收入品質：對計費目的有效且可接受 【可能是 ESPI 標準的延期，而非原始 ESPI 的一部分】

    

6. 在共用我的資料第三方廠商入口網站中發佈廠商 API 使用指標。

2018 年 11 月 15 日

新功能：

1. 已新增客戶類別指示器。每個授權的 SAID 將被識別為 RES、AGR、COM/IND 或其他。
2. 計費和使用 API 將更新為接受更新上限和更新上限查詢參數 （可替代已發佈上限和已發佈上限）。傳回的資料將是所有在更新最大值和更新最小值參數內發生的變更。
3. 將第三方的 5 位數大宗 ID 替換為第三方的客戶 ID 以進行線上授權流程。
4. 提供選項供第三方將客戶重新導向至 PG&E 的帳戶登入或來賓存取標籤，作為線上授權流程的一部分。
5. 改善 PG&E 的 Share My Data 客戶儀表板，讓客戶更容易與第三方檢視所有現有的資料分享授權。

2018 年 9 月 27 日

新功能：

作為 PG&E 擴展資料集 （EDS） 專案的一部分，PG&E 將新的資料元素新增到規則 24 資料集，相應的新資料元素則引入規則 25 資料集。包含 PG&E 擴充規則 25 資料集的特定資料元素，在下面以指定 EDS 列出：

規則 25 資料元素

Notes
帳戶項目
帳戶名稱
帳戶地址
帳戶 ID
EDS：停電區塊
服務項目
PG&E UUID
服務 ID
服務狀態
SA 狀態
服務開始日期
服務地址
目前服務收費
歷史服務收費
表選項（醫療基準、 照護， FERA， TBS、 CCA_TBS、 Solar Choice
電流服務電壓和商品歷史計費服務電壓
服務儀錶數量
服務儀錶數量
儀錶類型
電流儀錶讀取週期
歷史計費儀錶讀取週期
電流待命費率選項 如果現場發電指標
歷史計費待命費率選項
EDS： 客戶類別指示器
歷史帳單元素
帳單開始日期
帳單結束日期
帳單總金額（$）
帳單總金額 kWh
EDS： 服務提供者
名稱歷史帳單層級明細 （若有）
EDS： 明細項目帳單期間
EDS： 名稱（超過基準期 1%-30%）
EDS： 音量 （1234.2）
EDS： 費率（0美元。032/kWh）
EDS： 費用（$100。23）
歷史帳單 TOU kWh 明細（ABS-TX 計費除外）
EDS： 明細項目帳單期間 （針對 TOU 明細）
EDS： （ TOU 收費）
EDS 名稱： 音量 （1234.2）
EDS： 費率（0美元。032/kWh）
EDS： 費用（$100。23）
歷史帳單需量明細
EDS： 明細項目帳單期間（用於需求明細）
EDS： EDS 名稱
： 音量 （1234.2）
EDS： 費率（0美元。032/kWh）
EDS： 費用（$100。23）
歷史帳單明細項目
EDS： 明細項目帳單期間
EDS： 收費名稱 （DWR Bond Charge）
EDS： 音量 （1234.2）
EDS： 單位 （kWh）
EDS： 費率（0美元。032/kWh）
EDS： 費用（$100。23）

歷史使用間隔 間隔使用量 開始
預設間隔持續時間（以秒計）
間隔使用量 （1234.2）
單位 （kWh/Therms）
公用事業需求回應計畫
（DR） 計畫名稱
無財務義務
的最早終止日期 無財務義務 最早終止日期，無論財務義務
DR 計畫狀態
DR 計畫納入日期
DR 計畫取消納入日期
資料元素

商品當地時間參數（DST 詳細資料）
預設資料品質
能源方向
十倍增功率（用於間隔使用值）
功率 十倍增功率（用於計費需求）
功率 十倍增功率（用於計費總使用量）
間隔 長度（使用讀數）
總費用貨幣
電力間隔 TOU 指標

2018 年 6 月 28 日

作為 Click-Through 專案的一部分以及 Share My Data Platform 的持續改善，PG&E 於 2018 年 6 月 28 日推出 Click-Through Phase 2。

新功能：

影響第三方的最關鍵變更是符合 OAuth 2.0 協議的變更（PG&E 消除了最初一系列重新導向）。 詳情如下。

重要事項： 第三方必須變更其現有的 OAuth 實作。PG&E 的 Click-Through Phase 2 變更無法向後相容，因此第三方必須隨著 PG&E 的實施同時實施變更。若無實施，目前的客戶授權流程將於 2018 年 6 月 29 日停止運作。 但是，現有的授權不受影響。

1. 為了符合 OAuth 2.0 協議，PG&E 減少了用於授權的重新導向步驟數量。客戶登入和提交授權的初始重新導向至 PG&E 已與授權代碼請求合併如下：
   • 如以下範例所示，第三方授權碼要求現在包括將客戶的瀏覽器重新導向至 PG&E 的新authorizationServerAuthorizationEndpoint URI，以及適當的要求參數：
     取得 https://sharemydata.pge.com/myAuthorization?client_id=xxxxx&redirect_uri={redirect_uri}&response_type=code&state={optionalState}
   • 下列指標已淘汰：https://api.pge.com/datacustodian/oauth/v2/authorize...
     
2. 處理授權代碼要求之訊息時出現新的錯誤，且範圍參數遺失或無效，如下所示：
   • 如果所需的 client_id 或 redirect_uri 參數遺失或無效，向客戶顯示帶有解釋訊息的 （http 400） 錯誤
   • 如果所需的 response_type 參數遺失或無效，客戶將以 "invalid_request" 錯誤參數 （附加到 redirect_uri） 重新導向回第三方的 redirect_uri
     
3. 對於具有現有線上授權的客戶，第三方可以要求新的存取_金鑰/refresh_金鑰組，作為取代現有授權的一部分（即相同第三方的線上授權和客戶組合）。此功能可解決第三方遺失 access_token/refresh_token 配對或以其他方式需要根據客戶核准變更原始授權範圍的情況。
   • 對於重新授權請求，當第三方重新導向到 PG&E 進行授權時，客戶會看到新的授權頁面而不是“管理授權”頁面
   • 在客戶授權後，第三方會收到通知，告知其註冊的 URL 舊訂閱 ID 已取消 （通知包含舊訂閱 ID 的授權 API URL 端點）
     
4. 客戶透過驗證頁面或授權頁面上的 "cancel" 按鈕退出，並使用 "access_denied" 錯誤參數重新導向回第三方的 redirect_uri （附加至 redirect_uri）
5. 對於在 上以 "可見性" 設定註冊的第三方，因此包含在註冊的第三方清單中的第三方，客戶將在他們進入其 PG&E 線上帳戶時看到，並導覽至共用我的資料登陸頁面：
   • 對於登入其 PG&E 線上帳戶並導覽至共用我的資料登陸頁面，然後在從已註冊的第三方清單中選擇第三方時，重新導向至第三方已註冊的第三方入口網站 URI。屆時，客戶可以繼續進行第三方發起的 OAuth 流程。通過此路徑時，從第三方下拉式清單中選擇第三方後，客戶將不再看到授權頁面，而是被重新導向至第三方註冊的第三方入口網站 URI，在該處他們可以開始第三方發起的 OAuth 流程
   • ‭‬注意：部分第三方已詢問如何簡化此使用案例的客戶體驗 （即 PG&E 網站上啟動的授權），因此在從下拉清單中選取第三方時，似乎直接將它們帶往授權頁面。為了促進此類客戶體驗，第三方可以選擇將其第三方入口網站 URI（透過共用我的資料管理註冊頁面）設定為自動將客戶重新導向回 PG&E 的端點，作為授權代碼請求的一部分。自動重新導向回 PG&E authorizationServerAuthorizationEndpoint後，客戶將略過客戶登入頁面 （因為他們已經登入），並直接前往授權頁面。對於在 Share My Data Click Thru 2.0 版本之前已註冊的部分第三方，只需定義第三方入口網站 URI 以等於不再使用的 "第三方範圍選擇畫面"URI （舊的 SMD 註冊欄位將於未來版本中淘汰） 即可完成。
     相反地，有些第三方可能希望在客戶在要求授權代碼之前重新導向到他們的第三方入口網站的 URI 時，首先在他們那邊進行互動和篩選，因此上述方法只是一個建議。
     
6. SMD 現在將提供增強範圍參數詳細資料，作為對授權代碼請求、存取令牌請求和授權 API 的回應的一部分。增強範圍參數允許傳達客戶授權的最終範圍。具體而言，範圍參數包括對應至 PG&E 所支援之客戶授權資料群組選項的 "AdditionalScope" 值 （例如 "Usage"、"Billing"、"Basic"、"Account"、"Program Enrollment"）。根據以下文件進一步擷取範圍參數值：下載支援的功能模組範圍字串對應 按一下至 2.0 （PDF）
   
   以下金鑰回應範例說明一些可能的範圍參數值。
   • 動態密碼卡回應範例：
     ＜回應 xmlns="https：//api.第 頁com/datacustodian/oauth/v2/token">
     774ff105-7ad5-40c8-a6ec-f60675dc0e41
     3600
     998c6654-5b3b-4385-af4f-4e5c46c1bb04
     scope=FB=1_3_8_13_14_18_19_31_32_35_37_38_39_40_4_5_10_15_16_46_47AdditionalScope=Usage_Billing_Basic_Account_ProgramEnrollment；間隔持續時間=900_3600；BlockDuration=每日；HistoryLength={3P 註冊歷史長度}；AccountCollection={授權 SA 的數量}；BR={ThirdPartyID}；dataCustodianId=PGE
     資源URI：{資源URI}，例如： https：//api.第 頁com/GreenButtonConnect/espi/1_1/resource/Subscription/{subscriptionID}
     授權URI：{AuthorizationURI}，例如： https：//api.第 頁com/GreenButtonConnect/espi/1_1/resource/Authorization/{authorizationID}
     customerResourceURI：{customerResourceURI}，例如：https：//api.第 頁com/GreenButtonConnect/espi/1_1/resource/Batch/RetailCustomer/{RetailCustomerID}
     Bearer
     
     
     
7. 第三方現在可以註冊，透過新的“計劃註冊”資料組接收授權的計劃註冊資訊。間隔計量和非間隔計量客戶均有資格授權分享 SMD 點選至階段 2 的資料。計劃 Enrollment 資料群組所提供之新可用資料元素的高階摘要如下：
   • 計劃註冊（PG&E 需求回應計劃名稱/狀態和 CAISO 資訊）：
   • （帳單）帳戶地址
   • 服務協議狀態
   • （目前）服務費率
   • （目前） 維修電壓 （僅限電動）
   • 維修儀表編號（如有）
   • 儀錶類型
   • （目前）儀錶讀取週期
   • （當前）備用費率選項，如果現場產生指示器
   • （預設間隔使用時間） 持續時間 （長度單位為秒）
   • （已登記的 PG&E 需求回應）計劃名稱（如適用）
   • PG&E 無財務義務的註冊需求回應 （DR） 計劃最早終止日期
   • 無論財務義務為何，PG&E 登記需求回應 （DR） 計畫的最早終止日期
   • PG&E 需求回應 （DR） 計畫 （註冊） 狀態
   • PG&E 需量回應 （DR） 計劃註冊日期
   • PG&E 需量回應 （DR） 計劃取消註冊日期
   • 這些新資料元素的 Atom XML XSD （XML Schema Definition） 對應按照以下文件擷取：
     下載支援的資料元素 （PDF）
   • 關聯式資料階層模型根據以下方式概述：
     下載 PGE ESPI 資料模型 （PDF）
   • UsagePoint （亦稱 SA UUID）
     • ServiceDeliveryPoint\tariffProfile（目前服務費率表 AKA 費率表，包括備用費率選項，如適用）
     • readCycle（目前儀錶讀取週期）使用摘要
     • readCycle（帳單服務週期）
     • 商品 （包括電子帳單電壓位準）
     • tariffProfile （計費服務費率，包括備用費率選項，如適用
   • 讀取類型
     • 商品（包括電氣的目前電壓位準和備用費率選項的首碼，如適用）
   • 客戶帳戶
     • （帳戶帳單地址）：
     • mainAddress/streetDetail...
     • 主要地址/城鎮詳細資料...
     • mainAddress/postalCode...
   • 客戶協議
     • 狀態\值 （SA 狀態
   • 需求回應計畫
     • 程式名稱
     • 註冊狀態
     • 程式日期/程式日期
     • 程式日期/程式日期描述
   • 電錶
     • 序號 （公尺 ID）
     • 類型 （公尺類型）
     • （目前） 間隔長度
   • 用於這些新資料元素的最新 ESPI xml 架構定義 （XSD） 概述如下：
     下載 XSDs （ZIP， 49 KB）ZIP。在新視窗中開啟。
     注意：XSD 向下相容。
   • 第三方將能夠變更其註冊，以便允許客戶在授權期間透過第三方入口網站選擇此資料群組，其管理註冊 >編輯 > 部分：指出您需要的客戶資訊，選取計劃註冊核取方塊。
   • 注意：這僅適用於新客戶授權。
     
   • 用於擷取 DR 註冊資訊的新 API 可在大量第三方層級以及個別客戶授權層級 （RetailCustomerID 層級） 上取得，概述如下：
     下載新的 PGE 支援 API （PDF）
   • 非同步 API，用於要求與第三方取得所有授權的 DR Enrollment 資訊
     • https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/BulkRetailDRPrgInfo/{BulkID}
   • 用於在個別客戶授權層級要求 DR 註冊資訊的同步 API
     • https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Batch/RetailDRPrgInfo/{RetailCustomerID}

請注意：除了客戶授權流程的變更外，其他變更也向下相容，而且是第三方可選擇支援的自願增強功能。

如果您有任何疑問或需要額外支援，請隨時傳送電子郵件至 sharemydata@pge.com。

新功能：

1. 客戶現在可以從簡化的 Click-Through 授權程序中獲益。
   • 我們已更新客戶現在如何與貴公司分享資料的詳細資訊。
     瞭解客戶如何與公司分享資料
     
     附註： 這些變更，尤其是對授權 UI 的改進，已針對行動裝置（例如電話或平板電腦）進行最佳化。
   • 客戶可透過其 PG&E 線上帳戶存取的管理授權流程已變更：
     • 客戶仍然可以隨時從現有授權中移除 SAID、延長授權結束日期和/或取消授權。但是，若要新增其他 SAID 和/或變更授權資料元素，需要取消現有授權，並建立新的授權。
2. 如有需要，第三方現在可以使用此 API 透過 DELETE 作業來撤銷使用其第三方用戶端存取權杖 （在初始 SMD 第三方註冊程序中提供） 的個別客戶授權：https://api.pge.com/GreenButtonConnect/espi/1_1/resource/Authorization/{AuthorizationID}
   
   註釋 1：對於 PG&E 的實施， AuthorizationID 參數與 SubscriptionID 的值相同。
   
   附註 2：新的 API 讓第三方能夠撤銷（取消）授權。但是，只有客戶本身可以透過 SMD 管理授權頁面移除 SA ID 和/或更新授權結束日期。
   
   提醒：如同所有 API 資料要求，第三方必須先使用其最新的重新整理金鑰來要求新的金鑰配對（用戶端存取 + 重新整理金鑰）。
   
   動態密碼卡過期期間提醒：
   • 存取金鑰：1 小時
   • 用戶端存取金鑰：5 分鐘
   • 對應的重新整理權杖：1Yr
3. 第三方現在可以視需要使用相同的公司名稱和稅務 ID 建立多個共用我的資料 （SMD） 註冊。但是，顯示名稱 （客戶在授權時看到的名稱） 仍需要唯一。
   
   注意：以上所有變更皆向下相容，且為第三方可選擇支援的自願增強功能。下載此版本的支援文件：
   
   支援_APIS.SMD_CLICK-THRU_1.0 （PDF）
   
   支援_資料_元素_零售客戶.SMD_CLICK_THRU_1.0 （PDF）
   
   PGE_ESPI_DATA_MODEL.SMD_CLICK-THRU_1.0 （PDF）
   
   支援_資料_元素_ESPIDERIVED.SMD_CLICK_THRU_1.0 （PDF）
   
   ESPI_XSDS （ZIP）

2015 年 12 月 20 日

必要的變更：以下 SMD 2.0 更新需要變更第三方。

1. 考量到多個公用程式中除了 PG&E 以外，有 GBCMD（綠色按鈕連線我的資料）實作的第三方，我們會在 OAuth 授權序列期間，將資料重定向中的 CustodianID（即 dataCustodianID=PGE）傳回 ThirdPartyScopeSelectionScreenURI。
2. 接受日期參數的 API 請求（例如，批次請求）必須使用 Zulu 資料參數（例如，已發佈-最大/已發佈-最小）。不支援 API 要求中日期參數的其他日期格式。
   • 接受日期參數的 API 會依照附件的支援 APIs.xlsx 進行記錄
3. 間隔計量電力使用資料中包含的間隔 TOU 指示器 （如適用，指示每個間隔的 TOU 週期對應）
   • 請參考固定的計劃 ID 對應，詳細說明每個間隔 TOU 列舉的對應內容（例如 1 = 夏季高峰等）。（請參閱附件，支援的資料元素.xlsx）
4. 資料中發現的 client_idCustodianScopeSelectionScreenURI （用於第三方發起的 OAuth），以及在註冊測試期間應用程式資訊資源第三方請求中提供的 client_id，如果尚未更新為 5 位數 （例如新增前導零等）。此外，URL 結尾不再包含 '&verified=true'。第三方將需要相應更新其 URL。
   • 為詳細說明，資料CustodianScopeSelectionScreenURI 外觀如下：https://sharemydataqa.pge.com/myAuthorization/?clientId=XXXX （XXXX 為 clientID）
   • 因此，目前的用戶端 ID 為 123 會變更為 00123 之類的內容，代表他們的新資料CustodianScopeSelectionScreenURI 如下：
     https://sharemydataqa.pge.com/myAuthorization/?clientId=00123 （舊的 URL 如下：https://sharemydataqa.pge.com/myAuthorization/?clientId=00123&verified=true）
5. 註冊為“ESP”或“能源服務提供商”的第三方將更改為標準用戶類型。功能上沒有變更，僅在使用者類型標題中。區分 ESP 使用者類型 （與標準使用者類型不同） 是不必要的區分，在註冊過程中，在未提供任何差異化功能的情況下，會造成混淆，因此已淘汰。

可選增強功能： 以下變更向後相容，且為第三方可選擇支援的自願增強功能。

1. 第三方將能夠自動變更/更新其最初在註冊期間提供的 SSL 憑證（例如，憑證即將到期時），透過管理註冊 >編輯 > 新章節中的第三方入口網站進行：SSL 憑證資訊 （更新選項）。
2. 第三方可註冊以接收授權的基本帳單資訊、客戶資訊及氣體資料。  間隔計量和非間隔計量客戶均有資格授權共享 SMD 2.0 的資料。新可用資料元素的高層級摘要如下：
   • 帳單資訊：（適用於間隔和非間隔計量 SA）
     • 費率表、計費總計 美元、分層使用 （如適用）、需求 （如適用）、 TOU 總計 （如適用）
     • 注意：對於授權的非間隔計量客戶，第三方將只會收到帳單使用量總計 （即使用量摘要中） 且無間隔使用量讀取 （例如，因無法使用時每小時/每天讀取）
   • 客戶資訊：（適用於間隔和非間隔計量 SA）
     • 客戶名稱、服務地址、帳戶 ID、服務協議 ID、服務協議服務開始日期、
   • 間隔氣體使用資料：（僅限間隔計量氣體 SA）
     • 間隔（即每天）氣體讀數
   • 新資料元素會依照附件，支援的資料元素.xlsx 進行繪製
   • 隨附之 PGE ESPI Data Model.xlsx 中概述了關聯式資料階層
   • 用於這些新資料元素的最新 ESPI xml 架構定義 （XSD） 是根據附加的 XSD。注意：XSD 向下相容：
     • espiDerived.xsd（間隔使用和帳單資訊）
     • 零售客戶.xsd （客戶資訊）

如果您有任何疑問或需要其他支援，請隨時透過 ShareMyData@pge.com 與我們聯絡。

2015 年 12 月 18 日

必要的變更：以下 SMD 2.0 更新要求變更存取自己資料的部分使用者：

1. 接受日期參數的 API 請求（例如，批次請求）必須使用 Zulu 資料參數（例如，已發佈-最大/已發佈-最小）。不支援 API 要求中日期參數的其他日期格式。
   • 接受日期參數的 API 會依照附件的支援 APIs.xlsx 進行記錄
2. 間隔使用時間 （TOU） 指標包含於間隔計量電力使用資料中 （如適用，指示每個間隔的 TOU 週期對應）
   • 請參考固定的計劃 ID 對應，詳細說明每個間隔 TOU 列舉的對應內容（例如 1 = 夏季高峰等）。（請參閱附件，支援的資料元素.xlsx）

可選增強功能： 以下變更向後相容，且為第三方可選擇支援的自願增強功能。

1. 自我存取使用者將能夠自動變更/更新其最初在註冊期間提供的 SSL 憑證（例如，憑證即將到期時），透過管理註冊 > 編輯 > 新區段的第三方入口網站進行：SSL 憑證資訊 （更新選項）
2. 自我存取使用者註冊將更新，以包含授權的基本帳單資訊、客戶資訊和氣體資料。與非間隔計量服務協議一併計量的間隔，均有資格取得 SMD 2.0 的 （自我） 授權。新可用資料元素的高層級摘要如下：
   • 帳單資訊：（適用於間隔和非間隔計量 SA）
     • 費率表、計費總計 美元、分層使用 （如適用）、需求 （如適用）、 TOU 總計 （如適用）
     • 注意：對於授權的非間隔計量客戶，第三方將只會收到帳單使用量總計 （即使用量摘要中） 且無間隔使用量讀取 （例如，因無法使用時每小時/每天讀取）
   • 客戶資訊：（適用於間隔和非間隔計量 SA）
     • 客戶名稱、服務地址、帳戶 ID、服務協議 ID、服務協議服務開始日期、
   • 間隔氣體使用資料：（僅限間隔計量氣體 SA）
     • 間隔（即每天）氣體讀數
   • 新資料元素會依照附件，支援的資料元素.xlsx 進行繪製
   • 隨附之 PGE ESPI Data Model.xlsx 中概述了關聯式資料階層
   • 用於這些新資料元素的最新 ESPI xml 架構定義 （XSD） 是根據附加的 XSD。注意：XSD 向下相容：
     • espiDerived.xsd（間隔使用和帳單資訊）
     • 零售客戶.xsd （客戶資訊）

如果您有任何疑問或需要其他支援，請隨時透過 ShareMyData@pge.com 與我們聯絡。

2015 年 12 月 18 日

必要變更：以下 SMD 2.0 更新要求變更 CCA 實施的部分內容。

1. 必須使用 Zulu 時間日期參數提出特別要求 （例如：歷史資料）。不支援 API 要求中日期參數的其他日期格式。
2. 每日大量使用摘要將開始包含基本帳單資訊，而每日大量客戶摘要將包含其他客戶資訊。此新資料將提供給目前接收資料的間隔計量客戶，以及目前未接收資料的區域內非間隔計量客戶。最後，每日大量使用摘要中提供的間隔使用值將包括適用的間隔 TOU 指標。新資料元素的高層級摘要如下：
   • 帳單資訊：（適用於間隔和非間隔計量 SA）
     • 費率表、計費總計 美元、分層使用 （如適用）、需求 （如適用）、 TOU 總計 （如適用）
   • （額外）客戶資訊：（適用於間隔和非間隔計量 SA）
     • 客戶名稱、服務地址、服務協議服務開始日期、帳戶 ID
   • 間隔計量電力使用資料中包含的間隔 TOU 指示器 （如適用，指示每個間隔的 TOU 週期對應）
     • 請參考靜態程式 ID 對應，詳細說明每個間隔 TOU 列舉的對應項目（例如 1 = 夏季高峰等）。（請參閱附件，支援的資料元素.xlsx）
   • 用於這些新資料元素的最新 ESPI xml 架構定義 （XSD） 是根據附加的 XSD。請注意，XSD 向下相容：
     • espiDerived.xsd（間隔使用和帳單資訊）
     • 零售客戶.xsd （客戶資訊）
   • 新資料元素會依照附件、支援的資料元素.xlsx 進行繪製
   • 相關關係資料階層概述於附件 PGE ESPI Data Model.xlsx

可選增強功能： 以下變更向後相容，且為第三方可選擇支援的自願增強功能。

1. 除了收到的每日通知外，CCA 還可以在下列位置臨時要求客戶資訊：https://api.pge.com/GreenButtonConnect/espi/1_1/Batch/BulkRetailCustomerInfo/{BulkID} （在要求時返回客戶資訊的最新快照）。
2. CCA 在管理註冊 > 編輯 > 新區段下，將能夠透過第三方入口網站自動變更最初在註冊期間提供的 SSL 憑證 （例如，憑證即將到期）：SSL 憑證資訊 （更新選項）

如果您有任何疑問或需要額外支援，請隨時透過 ShareMyData@pge.com 與我們聯絡。

2015 年 8 月 21 日

新功能：

1. Oauth 回應中的狀態參數和資源 URI 變更
   • 作為 OAuth 授權代碼請求的一部分，第三方可以選擇傳送狀態參數，讓 PG&E 將傳送該參數回給第三方。PG&E 也會在成功完成授權時傳送授權代碼。此可選狀態參數可用於幫助第三方確定請求發起的位置，並將請求與其發起的授權相關聯。
   • 作為成功完成金鑰要求的一部分，我們會將 resourceURI 和 authorizationURI 與金鑰資訊分開分享。目前這些 URI 已翻轉，作為此版本的一部分，我們將更正它。

修正瑕疵：

1. 預設發佈日期-最大和發佈時間-最小
   目前 PG&E 要求第三方以發佈時間-最小和發佈時間-最大參數在 epoch 秒內為每個資料請求發送，以告知 PG&E 他們請求資料的持續時間。我們正在實施一項變更，以處理以下情境的要求：
   • 發佈-最小值和發佈-最大值缺失
   • 已發佈的最小值和已發佈的最大值以 UTC 為單位
   • 發佈的最小值和發佈的最大值以 epoch 秒為單位
   如果參數缺失，PG&E 將返回預設日期，而不是在此變更之前返回的錯誤訊息。在我們的案例中，預設是 T-2 日期的一天資料。如果參數存在且格式正確，我們將繼續尊重參數。
2. 修復授權 xml 中的日期
   目前在授權 xml 中，我們分享了發佈日期和授權日期。這些日期以毫秒為單位，而非以秒為單位，即標準。我們正在修復它，以便在 epoch 秒內傳回，而不是毫秒。
3. 針對 /resource/Subscription/{id}/UsagePoint/{id}/MeterReading/{id}/IntervalBlock 傳回不正確的 XML
   目前我們正在針對上述資源層級傳回不正確的回應 GET，其中 XML 的結構不正確，而且每個間隔重複項目，而不是在 24 小時內建立單一間隔區塊。
   
   這是固定的，24 個間隔區塊只會傳回單一間隔區塊。

問題或疑慮？ 請聯絡ShareMyData@pge.com。

• 客戶授權您透過 My Energy 和他們的 PG&E 線上帳戶存取其資料。如需客戶如何授權第三方或其他實體存取其資料的詳細概觀，請檢視共用我的資料第三方概觀。

前往授權詳細資料

• 目前沒有限制。

• 客戶可以選擇特定的時間長度，以便存取其資料，或者讓授權期間保持開放狀態。
• 您的應用程式可以透過呼叫授權資源 API（例如.../espi/1_1/resource/Authorization 和/或.../espi/1_1/resource/Authorization/{AuthorizationID}）來檢查客戶授權的結束日期和其他授權詳細資料。
• 或者，您也可以登入您的帳戶並選擇管理授權，手動檢查授權結束日期。

• 如果客戶選擇定義的授權期間，則其授權將在該期間結束時到期。如果他們取消授權，則其授權將在他們取消授權後的隔天到期。
• 如果客戶選擇無限期作為其授權期間，則其授權不會過期。請注意，考量到第 24 條要求回應提供者和使用共用我的資料的其他計畫，先前授權日期範圍的實際情況修正可在授權到期後最長三年內提供給第三方。
• 請參閱"將如何處理資料更正？" 以取得關於接收更正的進一步詳細資料。

• 任何 PG&E 客戶若目前擁有天然氣或電力服務的有效服務 ID，都可以授權您使用新的 Share My Data 工具來存取其資料。

• 我們非常鼓勵有興趣透過 Share My Data 計畫參與分享資料的客戶註冊 My Energy 帳戶。這將使整個流程更有效率，並使他們能夠線上管理授權。
• 客戶可以在授權過程中註冊 My Energy 帳戶。
• 客戶可以手動取得線上共用我的資料授權表單，並透過電子郵件提交填妥的表單。
• 有關手動流程的更多資訊，請透過 ShareMyData@pge.com 與我們聯絡。

• 客戶必須透過其 PG&E 線上帳戶進行線上授權。但是，如果他們填寫並簽署共享我的資料授權書，則您可以代表他們提交給 PG&E。

下載分享我的資料客戶授權或撤銷授權表單 （PDF， 308 KB）

• 您可以透過登入您的帳戶、導覽至管理註冊 > 編輯 > 並更新 OAuth 2.0 資訊區段下的欄位來更新您的 OAuth URI。

• 您可以透過登入您的帳戶、導覽至管理註冊 > 編輯 > 並更新資料存取資訊區段下的欄位來更新您的通知 URI。

• 您可以透過登入您的帳戶、導覽至管理註冊 > 編輯 > 並在 SSL 憑證資訊部分中選擇 "更新" 來更新您的 SSL 憑證。請注意，上傳新憑證可能需要幾天時間，才能使用新憑證更新 PG&E 系統。 
• 套用新憑證後，將傳送來自共用我的資料支援團隊的確認電子郵件。

• 收到表明您的註冊已被接受的電子郵件後，您將能夠登入您的 Share My Data 帳戶，並透過下載 PG&E SSL 憑證頁面下載我們的 SSL 憑證。

登入以分享我的資料

• 分享我的資料遵循綠色按鈕連接我的資料實施協議。Share My Data 也採用 OAuth 2.0 進行授權、傳輸層安全性 （TLS） 1.2 以及 NIST（國家標準與技術研究所）核准的最小網路安全通訊協定套件，因此不會明確交換任何資訊。

• 保護客戶資訊是 PG&E 的首要任務。 PG&E 會依據所有法律和法規要求，包括加州公共事業委員會和其他單位所建立的要求，將有關其客戶的資訊，包括個人資訊視為機密。 
• 二十多年來，PG&E 和加州其他投資者擁有的公用事業一直受到非常嚴格的 CPUC 法規的約束，這些法規禁止他們在未經客戶明確同意的情況下向第三方披露客戶特定資訊，例如帳單資料。 
• 一旦客戶授權釋出資料，客戶和第三方有責任保護這些資料。
• 客戶可隨時登入其 PG&E 線上帳戶並取消授權，以選擇停止與第三方分享資料。PG&E 的完整隱私政策和存取、收集、儲存、使用和披露能源使用資訊通知可在 pge.com/privacy 上找到。

• 在共用我的資料計畫的範圍內，第三方必須遵守共用我的資料平台條款與條件中指定的客戶資料隱私和保護規則，以及客戶資料存取費率中包含的要求。
• 第三方亦受與客戶隱私保護相關的所有其他適用法律法規的約束，包括但不限於 CPUC 採用的能源使用資料隱私和安全保護規則，如決策 11-07-056（電子）的附件 D，也歸納於 PG&E 的電氣規則第 27 條和加州民法第 1798.80 – 1798.84 節。
• 如需更多資訊，請選擇以下連結：
  分享我的資料條款與條件（PDF， 190 KB）
  電子規則第 27 號 （PDF， 1.6 MB）
  決策 11-07-056 附件 D （PDF）
  尋找更多資訊：加州民法第 1798.80 – 1798.84 節

• 請參閱下方連結，以取得所支援資料元素的詳細清單。

取得更多關於資料存取的資訊

• 有時候，由於我們的上游資料驗證流程發現資料讀取遺失或不正確，可能需要進一步處理（編輯和/或估計），因此缺少間隔使用資料。
• 對於週期性計費客戶 （例如，有使用時間計費考量的客戶），這些執行個體會及時更正，以確保其即將到來的每月帳單上能準確計算帳單。

• 如果您想接收資料更正，請確保您在註冊時勾選通知我為就緒資料核取方塊，或登入您的線上帳戶並勾選編輯設定檔下的此核取方塊。然後，針對您獲授權存取的任何資料，我們將納入我們系統在過去 24 小時內擷取的資料更正，作為每日使用摘要的一部分。
• 資料更正將涵蓋授權期間的任何變更，最長三年。

註：考量到第 24 條要求回應提供者及其他使用共享我的資料之程式，先前授權日期範圍之事後修正，得於授權屆滿後最長三年內提供給第三方。

• 如適用，PG&E 將發送通知至您在註冊時提供的通知 URL。通知包含對應於已預先包裝資料的 URL，供您返回並使用提供的 URL 請求。資料已預先封裝，並在以下兩種情況下發送通知：（1） 您已在註冊檔案中選擇“資料已就緒時通知我”，在這種情況下，我們將把最新的每日資料與過去日期的任何更正進行封裝，或者（2）您提前提出了一個臨時非同步請求，請求的資料現已準備就緒。情境 1 說明於 "DATA ACCESS：資料存取頁面上的資料存取方法圖表和情境 2 的每日訂閱部分如資料存取：AD HOC REQUEST （ASYNCHRONOUS）" 部分也位於資料存取頁面。

就診資料存取以上

• Share My Data 所提供的電力使用資料並非加州獨立系統營運商 （CAISO） 所指定的結算品質儀資料 （SQMD）。SQMD 的產生方式是將營收品質計資料 （RQMD） 乘以適用於該客戶的該間隔電壓位準的分配損失係數 （DLF），將計量間隔轉換為 CAISO 所需的間隔期間，然後將每個間隔的結果加總至 CAISO 所需的彙總位準。
  
• PG&E 正在實施 ESPI 標準提供的 "QualityOfReading" （QOR） 類型的旗標，以傳達資料是否為營收品質。QOR 類型擷取不同的使用資料可能品質值，包括“營收品質計資料”或“RQMD”的明確值。PG&E 將在資料傳輸中使用此 QOR 類型，如下所示：
  • PG&E 支援 ESPI 提供的 "UsageSummary" 類別，該類別將用於識別服務協議的計費日期、計費使用金額，以及申請時的使用資料品質。一旦帳單可用於要求的資料，便會填入使用摘要，並包含兩個 QOR 類型的旗標（元素）：
    • UsageSummary.QualityOfReading 元素 （在 UsageSummary 層級） 指出在要求時提供的最新間隔使用值加上對應於 UsageSummary.billing 期間日期的更正的品質。
    • 表示總計費使用量品質的 OverallConsumptionLastPeriod （作為 UsageSummary.OverallConsumptionLastPeriod.ReadingTypeRef 的一部分） 預設品質元素。
  • PG&E 也會使用 IntervalReading.ReadingQuality.Quality 元素，在要求時的間隔層級傳達使用資料的品質。

• 在註冊期間，您可以在“需要多少歷史資料”下拉選單中選擇您需要多少歷史資料，可以是24個月、36個月或48個月。
• 作為客戶授權允許您存取其資料的一部分，授權歷史期間將預設為授權中所包含的服務 ID（使用點）的註冊選擇。
• 您可以透過登入您的帳戶、導覽至管理註冊 > 編輯 > 並從標記為“需要多少歷史資料”的下拉選單中選擇來更新您請求的歷史資料。
• 請注意，歷史請求中提供的資料將從客戶授權的日期開始，而不是您向 API 請求的日期。

注意：您要求的歷史資料變更僅影響新客戶授權，而先前客戶授權將反映您在授權時的選擇。

• 根據 ESPI 標準，回應使用 Atom Publishing Standard。請選擇以下連結，以查看支援 API 的完整清單，以及可用資料元素。

取得更多關於資料存取的資訊

• 由 PG&E 安裝和讀取的有效電力和天然氣服務 ID 有資格透過 Share My Data 平台取得授權。
• 如果由於以下原因之一導致與授權相關的服務 ID 發生變更，則授權將轉移到新的服務 ID，並且將繼續存取歷史間隔使用資料：
  • 因未付款而暫時關閉
  • 移至間隔計費
  • 更換血糖機
  • 費率變更
• 導致服務 ID 變更的其他情況，例如移動地點或公司變更，將終止存取。此外，如果帳戶與您的 My Energy 帳戶取消連結，所有透過共用我的資料授權的基礎服務 ID 將因此遭到未授權。

• 若要判斷授權間隔資料的精細度，請參考 ESPI 標準提供的間隔長度元素。
• PG&E 以與計費目的收集的間隔使用資料相同的精細度提供間隔使用資料，通常以每小時或 15 分鐘為基準，而對於具有間隔儀的客戶，則以每日為基準提供間隔使用資料。雖然它可能因客戶而異，但對於大多數住宅客戶，電間隔儀的使用量通常按小時計算，對於大多數商業客戶，電間隔儀的使用量通常按 15 分鐘計算，對於大多數客戶，氣間隔儀的使用量通常按每日計算。
• 對於非間隔儀表，將在可用時提供資料。

• 對於已安裝智慧電錶的大多數 PG&E 客戶而言，電力和瓦斯間隔使用資料可在次日結束前透過 Share My Data 平台取得。
• 已安裝電線載波 MV90 公尺的 PG&E 電力客戶中，有一小部分可能需要額外的時間才能取得資料。

• 雖然我們無法直接支援您的 API 設定，但我們確實有許多資源可供協助您的 IT 和技術資源進行開發程序。請參閱我們的 API 文件頁面以瞭解更多資訊。如有任何其他問題，請隨時聯絡ShareMyData@pge.com。

如需更多資訊，請造訪應用程式開發介面 （API）