DualSoft

AAS API 식별자 Base64URL 변환기와 인코딩 규칙

AAS REST API는 AAS, Submodel, ConceptDescription의 id를 URL에 그대로 넣지 않고 base64url로 바꿔 넣습니다. 규칙은 짧지만 문자 집합이나 패딩을 하나만 틀려도 서버가 id를 찾지 못할 수 있습니다. Part 2 v3.2 원문과 RFC 4648을 기준으로 정리합니다.

기준 규격: AAS Part 2 API (IDTA-01002) v3.2 HTTP/REST Design Decisions, RFC 4648 §5수정 2026-11-17

Base64url 변환기

/shells/aHR0…/submodels/aHR0… 같은 주소를 통째로 붙여 넣고 «디코딩»을 누르면 주소 안의 식별자를 모두 풉니다.

base64url (패딩 없음 · AAS API 규칙)
base64url (패딩 포함)
디코딩 결과

브라우저 안에서만 계산하며 입력값을 어디에도 보내지 않습니다.

왜 base64url로 넣는가

AAS의 id는 보통 IRI, URN, IRDI입니다. 예를 들어 https://admin-shell.io/idta/nameplate/3/0/Nameplate이나 0112/2///61987#ABA565#009 같은 값입니다.이 값을 경로에 그대로 넣으면 /는 경로 구분자로, # 은 프래그먼트로, ? 는 쿼리 시작으로 해석됩니다.

그래서 Part 2는 Identifiable(AAS, Submodel, ConceptDescription)의 id를 base64url로 인코딩해 API에 넘기도록 정합니다. AASX File Server의 packageId, 비동기 작업의 handleId, 쿼리 파라미터 semanticId와 assetIds도 base64url로 넘깁니다.

규칙 (Part 2 v3.2 기준)

  • 알파벳은 RFC 4648 §5의 URL-safe 알파벳입니다. 표준 base64의 + 대신 -, / 대신 _를 씁니다.
  • 패딩 문자 =는 넣지 않습니다. Part 2는 base64url 값이 =를 포함하거나 =로 끝나면 안 된다고 적습니다(v3.1에서 명시).
  • 인코딩 대상은 문자열의 UTF-8 바이트 배열입니다.
  • semanticId 쿼리는 Reference를 JSON으로 직렬화한 다음 base64url로 인코딩합니다. assetIds는 SpecificAssetId를 같은 방식으로 인코딩합니다. 인코딩된 semanticId는 최대 3072자입니다(Constraint AASa-002).
  • idShortPath는 대상이 아닙니다. idShortPath는 URL 인코딩합니다.
  • 결과는 A-Z, a-z, 0-9, -, _만으로 이루어집니다. 모두 RFC 3986의 비예약 문자이므로 다시 퍼센트 인코딩할 필요가 없습니다.

단계별 인코딩 예시

https://example.com/ids/aas/센서-01을 인코딩해 보겠습니다. (1) UTF-8 바이트로 바꿉니다. 한글 두 글자가 6바이트라 모두 37바이트입니다. (2) 표준 base64로 인코딩하면 aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvYWFzL+yEvOyEnC0wMQ==입니다. (3) +를 -로, /를 _로 바꿉니다. (4) 끝의 ==를 지웁니다. 결과는 aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvYWFzL-yEvOyEnC0wMQ이고, 요청은 GET /shells/aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvYWFzL-yEvOyEnC0wMQ이 됩니다.

표의 값은 Python base64.urlsafe_b64encode 결과에서 =를 지운 것입니다. 첫 줄은 Part 2 본문의 예와 같습니다. 넷째 줄은 표준 base64로 하면 _ 자리에 /가 들어갑니다.

semanticId 쿼리 예: Reference {"type":"ExternalReference","keys":[{"type":"GlobalReference","value":"https://admin-shell.io/idta/nameplate/3/0/Nameplate"}]}를 공백 없이 직렬화해 인코딩하면 GET /submodels?semanticId=eyJ0eXBlIjoiRXh0ZXJuYWxSZWZlcmVuY2UiLCJrZXlzIjpbeyJ0eXBlIjoiR2xvYmFsUmVmZXJlbmNlIiwidmFsdWUiOiJodHRwczovL2FkbWluLXNoZWxsLmlvL2lkdGEvbmFtZXBsYXRlLzMvMC9OYW1lcGxhdGUifV19가 됩니다. Part 2는 JSON 공백 차이로 인코딩 문자열이 달라질 수 있지만 서버는 원래 내용으로 처리해야 한다고 적습니다.

원래 값base64url (패딩 없음)
https://admin-shell.io/sampleSMaHR0cHM6Ly9hZG1pbi1zaGVsbC5pby9zYW1wbGVTTQ
https://admin-shell.io/idta/nameplate/3/0/NameplateaHR0cHM6Ly9hZG1pbi1zaGVsbC5pby9pZHRhL25hbWVwbGF0ZS8zLzAvTmFtZXBsYXRl
0112/2///61987#ABA565#009MDExMi8yLy8vNjE5ODcjQUJBNTY1IzAwOQ
https://example.com/aas/valve?v=1aHR0cHM6Ly9leGFtcGxlLmNvbS9hYXMvdmFsdmU_dj0x
https://example.com/ids/aas/센서-01aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvYWFzL-yEvOyEnC0wMQ

디코딩

되돌릴 때는 순서를 반대로 합니다. -를 +로, _를 /로 바꾸고, 길이가 4의 배수가 되도록 =를 붙인 뒤 표준 base64로 디코딩합니다. 마지막으로 바이트를 UTF-8로 읽습니다.

길이를 4로 나눈 나머지가 2이면 ==를, 3이면 =를 붙입니다. 나머지가 1이면 올바른 base64url 값이 아닙니다. Python의 base64.urlsafe_b64decode는 패딩이 없으면 Incorrect padding 오류를 내므로 패딩을 먼저 채워야 합니다.

자주 하는 실수

  • 표준 base64를 쓰는 경우: 값에 /가 들어가면 경로가 갈라지고, +는 쿼리에서 공백으로 읽힐 수 있습니다.
  • 패딩 =를 남기는 경우: 명세 위반입니다. 라이브러리 기본값이 패딩을 붙이는지 확인합니다.
  • 이중 인코딩: id를 먼저 퍼센트 인코딩(https%3A%2F%2F...)한 뒤 base64url로 바꾸면 전혀 다른 문자열이 됩니다. 인코딩 결과를 다시 퍼센트 인코딩할 필요도 없습니다.
  • UTF-8이 아닌 경우: CP949 같은 다른 문자 인코딩으로 바이트를 만들면 한글 id의 결과가 달라집니다. 브라우저의 btoa는 한글 문자열을 바로 받지 못하므로 TextEncoder로 먼저 UTF-8 바이트를 만듭니다.
  • idShortPath를 base64url로 바꾸는 경우: idShortPath는 URL 인코딩입니다. 예: sme1.sme2[0].p1은 sme1.sme2%5B0%5D.p1.
  • 대소문자를 바꾸는 경우: base64url은 대소문자를 구분합니다. URL을 소문자로 정규화하는 프록시나 코드는 값을 망가뜨립니다.

Python 예제

표준 라이브러리만 씁니다. 디코딩 함수는 패딩이 있든 없든 받아들입니다.

import base64

def encode_id(identifier: str) -> str:
    """AAS identifier -> base64url without padding (IDTA-01002)."""
    raw = base64.urlsafe_b64encode(identifier.encode("utf-8"))
    return raw.decode("ascii").rstrip("=")

def decode_id(encoded: str) -> str:
    """base64url (with or without padding) -> identifier."""
    padded = encoded + "=" * (-len(encoded) % 4)
    return base64.urlsafe_b64decode(padded).decode("utf-8")

sm_id = "https://example.com/ids/aas/센서-01"
enc = encode_id(sm_id)
print(enc)   # aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvYWFzL-yEvOyEnC0wMQ
assert decode_id(enc) == sm_id

# idShortPath is URL-encoded, not base64url
from urllib.parse import quote
print(quote("sme1.sme2[0].p1", safe=""))   # sme1.sme2%5B0%5D.p1

JavaScript 예제

브라우저와 Node.js에서 모두 동작합니다. Node.js에서는 Buffer의 base64url 인코딩도 패딩 없이 같은 결과를 냅니다.

// Works in browsers and Node.js (TextEncoder, btoa, atob)
function encodeId(id) {
  const bytes = new TextEncoder().encode(id);          // UTF-8
  let bin = "";
  for (const b of bytes) bin += String.fromCharCode(b);
  return btoa(bin)
    .replace(/\+/g, "-").replace(/\//g, "_")       // RFC 4648 section 5
    .replace(/=+$/, "");                              // no padding
}

function decodeId(s) {
  let b64 = s.replace(/-/g, "+").replace(/_/g, "/");
  b64 += "=".repeat((4 - (b64.length % 4)) % 4);
  const bytes = Uint8Array.from(atob(b64), c => c.charCodeAt(0));
  return new TextDecoder().decode(bytes);
}

encodeId("https://admin-shell.io/sampleSM");
// "aHR0cHM6Ly9hZG1pbi1zaGVsbC5pby9zYW1wbGVTTQ"
// Node.js only: Buffer.from(id, "utf8").toString("base64url") gives the same result.

자주 묻는 질문

aHR0cHM6Ly…로 시작하는 문자열은 무엇인가요?

https://로 시작하는 식별자를 base64url(또는 base64)로 인코딩한 값입니다. https://는 항상 aHR0cHM6Ly로, http://는 aHR0cDovL로 시작합니다. 이 쪽의 변환기에 붙여 넣고 «디코딩»을 누르면 원래 id가 나옵니다.

base64url과 base64는 무엇이 다른가요?

RFC 4648 표에서 값 62와 63에 해당하는 두 문자만 다릅니다. base64는 +와 /를, base64url은 -와 _를 씁니다. AAS API는 여기에 더해 패딩 =를 빼도록 정합니다.

서버에서 404가 나는데 id는 맞습니다. 무엇을 확인하나요?

인코딩 결과에 +, /, =가 있는지, id 앞뒤에 공백이나 줄바꿈이 섞이지 않았는지, UTF-8로 인코딩했는지 확인합니다. 그다음 디코딩해서 원래 id와 글자 하나까지 같은지 비교합니다.

Submodel의 semanticId로 검색할 때도 IRI 문자열만 인코딩하면 되나요?

Part 2는 semanticId 쿼리에 Reference 전체를 JSON으로 직렬화한 뒤 base64url로 넣으라고 정합니다. 경로의 id와 달리 문자열 하나가 아니라 Reference 객체를 인코딩한다는 점이 다릅니다.

함께 보면 좋은 글

근거 규격·출처

← 가이드 전체 보기